Adding migration guide for 3.0.0 release.

Author: twitchax

documentation/release-notes/migration-guide.3.0.0.md

@@ -0,0 +1,117 @@
+# Breaking changes for Microsoft Azure PowerShell 3.0.0.
+
+This document serves as both a breaking change notification and migration guide for consumers of the Microsoft Azure PowerShell cmdlets.  Each section describes both the impetus for the breaking change and the migration path of least resistance.  For in-depth context, please refer to the pull request associated with each change.
+
+## Table of Contents
+1. [Breaking changes to Data Lake Store cmdlets](#breaking-changes-to-data-lake-store-cmdlets)
+2. [Breaking changes to ApiManagement cmdlets](#breaking-changes-to-apimanagement-cmdlets)
+3. [Breaking changes to Network cmdlets](#breaking-changes-to-network-cmdlets)
+
+## Breaking changes to Data Lake Store cmdlets
+
+The following cmdlets were affected this release ([PR 2965](https://github.com/Azure/azure-powershell/pull/2965)):
+
+**Get-AzureRmDataLakeStoreItemAcl (Get-AdlStoreItemAcl)**
+- This cmdlet was removed and replaced with ``Get-AzureRmDataLakeStoreItemAclEntry (Get-AdlStoreItemAclEntry)``.
+- The old cmdlet returned a complex object representing the access control list (ACL). The new cmdlet returns a simple list of entries in the chosen path's ACL.
+
+```powershell
+# Old
+Get-AdlStoreItemAcl -Account myadlsaccount -Path /foo
+
+# New
+Get-AdlStoreItemAclEntry -Account myadlsaccount -Path /foo
+```
+
+**Get-AzureRmDataLakeStoreItemAclEntry (Get-AdlStoreItemAclEntry)**
+- This cmdlet replaces the old cmdlet ``Get-AzureRmDataLakeStoreItemAcl (Get-AdlStoreItemAcl)``.
+- This new cmdlet returns a simple list of entries in the chosen path's ACL, with type ``DataLakeStoreItemAce[]``.
+- The output of this cmdlet can be passed in to the ``-Acl`` parameter of the following cmdlets:
+   - ``Remove-AzureRmDataLakeStoreItemAcl``
+   - ``Set-AzureRmDataLakeStoreItemAcl``
+   - ``Set-AzureRmDataLakeStoreItemAclEntry``
+
+```powershell
+# Old
+Get-AdlStoreItemAcl -Account myadlsaccount -Path /foo
+
+# New
+Get-AdlStoreItemAclEntry -Account myadlsaccount -Path /foo
+```
+
+**Remove-AzureRmDataLakeStoreItemAcl (Remove-AdlStoreItemAcl)**, **Set-AzureRmDataLakeStoreItemAcl (Set-AdlStoreItemAcl)**, **Set-AzureRmDataLakeStoreItemAclEntry (Set-AdlStoreItemAclEntry)**
+- These cmdlets now accept ``DataLakeStoreItemAce[]`` for the ``-Acl`` parameter.
+- ``DataLakeStoreItemAce[]`` is returned by ``Get-AzureRmDataLakeStoreItemAclEntry (Get-AdlStoreItemAclEntry)``.
+
+```powershell
+# Old
+$acl = Get-AdlStoreItemAcl -Account myadlsaccount -Path /foo
+Set-AdlStoreItemAcl -Account myadlsaccount -Path /foo -Acl $acl
+
+# New
+$aclEntries = Get-AdlStoreItemAclEntry -Account myadlsaccount -Path /foo
+Set-AdlStoreItemAcl -Account myadlsaccount -Path /foo -Acl $aclEntries
+```
+
+## Breaking changes to ApiManagement cmdlets
+
+The following cmdlets were affected this release ([PR 2971](https://github.com/Azure/azure-powershell/pull/2971)):
+
+**New-AzureRmApiManagementVirtualNetwork**
+- The required parameters to reference a virtual network changed from requiring SubnetName and VnetId to SubnetResourceId in format 
+``/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ClassicNetwork/virtualNetworks/{virtualNetworkName}/subnets/{subnetName}``
+
+```powershell
+# Old
+$virtualNetwork = New-AzureRmApiManagementVirtualNetwork -Location <String> -SubnetName <String> -VnetId <Guid>
+
+# New
+$virtualNetwork = New-AzureRmApiManagementVirtualNetwork -Location <String> -SubnetResourceId <String>
+
+```
+
+**Deprecating Cmdlet Set-AzureRmApiManagementVirtualNetworks**
+- The Cmdlet is getting deprecated as there was more than one way to Set Virtual Network associated to ApiManagement deployment.
+
+```powershell
+# Old
+$networksList = @()
+$networksList += New-AzureRmApiManagementVirtualNetwork -Location $vnetLocation -VnetId $vnetId -SubnetName $subnetName
+Set-AzureRmApiManagementVirtualNetworks -ResourceGroupName "ContosoGroup" -Name "ContosoApi" -VirtualNetworks $networksList
+
+# New
+$masterRegionVirtualNetwork = New-AzureRmApiManagementVirtualNetwork -Location <String> -SubnetResourceId <String>
+Update-AzureRmApiManagementDeployment -ResourceGroupName "ContosoGroup" -Name "ContosoApi" -VirtualNetwork $masterRegionVirtualNetwork
+```
+
+## Breaking changes to Network cmdlets
+
+The following cmdlets were affected this release ([PR 2982](https://github.com/Azure/azure-powershell/pull/2982)):
+
+**New-AzureRmVirtualNetworkGateway**
+- Description of what has changed ``:- Bool parameter:-ActiveActive`` is removed and ``SwitchParameter:-EnableActiveActiveFeature`` is added for enabling Active-Active feature on newly creating virtual network gateway.
+
+```powershell
+# Old 
+# Sample of how the cmdlet was previously called
+New-AzureRmVirtualNetworkGateway -ResourceGroupName $rgname -name $rname -Location $location -IpConfigurations $vnetIpConfig1,$vnetIpConfig2 -GatewayType Vpn -VpnType RouteBased -EnableBgp $false -GatewaySku HighPerformance -ActiveActive $true
+
+# New
+# Sample of how the cmdlet should now be called
+New-AzureRmVirtualNetworkGateway -ResourceGroupName $rgname -name $rname -Location $location -IpConfigurations $vnetIpConfig1,$vnetIpConfig2 -GatewayType Vpn -VpnType RouteBased -EnableBgp $false -GatewaySku HighPerformance -EnableActiveActiveFeature
+```
+
+Set-AzureRmVirtualNetworkGateway
+- Description of what has changed ``:- Bool parameter:-ActiveActive`` is removed and 2 ``SwitchParameters:-EnableActiveActiveFeature`` / ``DisableActiveActiveFeature`` are added for enabling and disabling Active-Active feature on virtual network gateway.
+
+```powershell
+# Old
+# Sample of how the cmdlet was previously called
+Set-AzureRmVirtualNetworkGateway -VirtualNetworkGateway $gw -ActiveActive $true
+Set-AzureRmVirtualNetworkGateway -VirtualNetworkGateway $gw -ActiveActive $false  
+
+# New
+# Sample of how the cmdlet should now be called
+Set-AzureRmVirtualNetworkGateway -VirtualNetworkGateway $gw -EnableActiveActiveFeature
+Set-AzureRmVirtualNetworkGateway -VirtualNetworkGateway $gw -DisableActiveActiveFeature
+```