Azure · markcowl · Aug 9, 2016 · Aug 8, 2016
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -1,5 +1,5 @@
 ##2016.08.03 version 2.0.0
-* This release contains breaking changes. Please see [the migration guide](https://gist.github.com/cormacpayne/dad22c060dfd9acfda744f1405d4539c) for change details and the impact on existing scripts.
+* This release contains breaking changes. Please see [the migration guide](documentation/release-notes/migration-guide.2.0.0.md) for change details and the impact on existing scripts.
 * Removal of Force parameters that were marked as obsolete in the previous release
   * ApiManagement
     - Remove-AzureRmApiManagement

diff --git a/documentation/release-notes/migration-guide.2.0.0.md b/documentation/release-notes/migration-guide.2.0.0.md
@@ -0,0 +1,321 @@
+# Table of Contents
+1. [Removal of Force parameters](#removal-of-force-parameters)
+2. [Change of Tag parameters](#change-of-tag-parameters)
+3. [Breaking changes to Storage cmdlets](#breaking-changes-to-storage-cmdlets)
+4. [Breaking changes to AD cmdlets](#breaking-changes-to-ad-cmdlets)
+
+## Removal of Force parameters
+
+This release, we removed all Obsolete `Force` parameters from cmdlets and the corresponding warnings that the parameter would be removed in a future release.
+
+The following cmdlets are affected by this change:
+
+**ApiManagement**
+- Remove-AzureRmApiManagement
+- Remove-AzureRmApiManagementApi
+- Remove-AzureRmApiManagementGroup
+- Remove-AzureRmApiManagementLogger
+- Remove-AzureRmApiManagementOpenIdConnectProvider
+- Remove-AzureRmApiManagementOperation
+- Remove-AzureRmApiManagementPolicy
+- Remove-AzureRmApiManagementProduct
+- Remove-AzureRmApiManagementProperty
+- Remove-AzureRmApiManagementSubscription
+- Remove-AzureRmApiManagementUser
+
+**Automation**
+- Remove-AzureRmAutomationCertificate
+- Remove-AzureRmAutomationCredential
+- Remove-AzureRmAutomationVariable
+- Remove-AzureRmAutomationWebhook
+
+**Batch**
+- Remove-AzureBatchCertificate
+- Remove-AzureBatchComputeNode
+- Remove-AzureBatchComputeNodeUser
+
+**DataFactories**
+- Resume-AzureRmDataFactoryPipeline
+- Set-AzureRmDataFactoryPipelineActivePeriod
+- Suspend-AzureRmDataFactoryPipeline
+
+**DataLakeStore**
+- Remove-AzureRmDataLakeStoreItemAclEntry
+- Set-AzureRmDataLakeStoreItemAcl
+- Set-AzureRmDataLakeStoreItemAclEntry
+- Set-AzureRmDataLakeStoreItemOwner
+
+**OperationalInsights**
+- Remove-AzureRmOperationalInsightsSavedSearch
+
+**Profile**
+- Remove-AzureRmEnvironment
+
+**RedisCache**
+- Remove-AzureRmRedisCacheDiagnostics
+
+**Resources**
+- Register-AzureRmProviderFeature
+- Register-AzureRmResourceProvider
+- Remove-AzureRmADServicePrincipal
+- Remove-AzureRmPolicyAssignment
+- Remove-AzureRmResourceGroupDeployment
+- Remove-AzureRmRoleAssignment
+- Stop-AzureRmResourceGroupDeployment
+- Unregister-AzureRmResourceProvider
+
+**Storage**
+- Remove-AzureStorageContainerStoredAccessPolicy
+- Remove-AzureStorageQueueStoredAccessPolicy
+- Remove-AzureStorageShareStoredAccessPolicy
+- Remove-AzureStorageTableStoredAccessPolicy
+
+**StreamAnalytics**
+- Remove-AzureRmStreamAnalyticsFunction
+- Remove-AzureRmStreamAnalyticsInput
+- Remove-AzureRmStreamAnalyticsJob
+- Remove-AzureRmStreamAnalyticsOutput
+
+**Tag**
+- Remove-AzureRmTag
+
+<br>
+
+If you have a script that uses any of the above cmdlets, the breaking change can be fixed by simply removing the `Force` parameter.
+
+```powershell
+# Old
+New-AzureRmResourceGroup -Name $resourceGroupName -Location $location -Force
+
+# New
+New-AzureRmResourceGroup -Name $resourceGroupName -Location $location
+```
+
+<br>
+
+## Change of Tag parameters
+
+This release, the `Tags` parameter name was changed to `Tag`, and the type was changed from `Hashtable[]` to `Hashtable`, changing the format of the key-value pairings.
+
+Previously, each entry in the `Hashtable[]` represented a single key-value pairing:
+
+```powershell
+$tags = @{ Name = "test1"; Value = "testval1" }, @{ Name = "test2", Value = "testval2" }
+$tags[0].Name  # Key for the first entry, "test1"
+$tags[0].Value # Value for the first entry, "testval1"
+$tags[1].Name  # Key for the second entry, "test2"
+$tags[1].Value # Value for the second entry, "testval2"
+```
+
+Now, `Name` and `Value` are no longer necessary, allowing for key-value pairings to be created by assigning `Key = "Value"` in the `Hashtable`:
+
+```powershell
+$tag = @{ test1 = "testval1"; test2 = "testval2" }
+$tag["test1"] # Gets the value associated with the key "test1"
+$tag["test2"] # Gets the value associated with the key "test2"
+```
+
+The following cmdlets are affected by this change:
+
+**Batch**
+- Get-AzureRmBatchAccount
+- New-AzureRmBatchAccount
+- Set-AzureRmBatchAccount
+
+**Compute**
+- New-AzureRmVM
+- Update-AzureRmVM
+
+**DataLakeAnalytics**
+- New-AzureRmDataLakeAnalyticsAccount
+- Set-AzureRmDataLakeAnalyticsAccount
+
+**DataLakeStore**
+- New-AzureRmDataLakeStoreAccount
+- Set-AzureRmDataLakeStoreAccount
+
+**Dns**
+- New-AzureRmDnsZone
+- Set-AzureRmDnsZone
+
+**KeyVault**
+- Get-AzureRmKeyVault
+- New-AzureRmKeyVault
+
+**Network**
+- New-AzureRmApplicationGateway
+- New-AzureRmExpressRouteCircuit
+- New-AzureRmLoadBalancer
+- New-AzureRmLocalNetworkGateway
+- New-AzureRmNetworkInterface
+- New-AzureRmNetworkSecurityGroup
+- New-AzureRmPublicIpAddress
+- New-AzureRmRouteTable
+- New-AzureRmVirtualNetwork
+- New-AzureRmVirtualNetworkGateway
+- New-AzureRmVirtualNetworkGatewayConnection
+- New-AzureRmVirtualNetworkPeering
+
+**Resources**
+- Find-AzureRmResource
+- Find-AzureRmResourceGroup
+- New-AzureRmResource
+- New-AzureRmResourceGroup
+- Set-AzureRmResource
+- Set-AzureRmResourceGroup
+
+**SQL**
+- New-AzureRmSqlDatabase
+- New-AzureRmSqlDatabaseCopy
+- New-AzureRmSqlDatabaseSecondary
+- New-AzureRmSqlElasticPool
+- New-AzureRmSqlServer
+- Set-AzureRmSqlDatabase
+- Set-AzureRmSqlElasticPool
+- Set-AzureRmSqlServer
+
+**Storage**
+- New-AzureRmStorageAccount
+- Set-AzureRmStorageAccount
+
+**TrafficManager**
+- New-AzureRmTrafficManagerProfile
+
+<br>
+
+If you have a script that uses any of the above cmdlets, the breaking change can be fixed by changing the `Tags` parameter to `Tag`, as well as changing the `Tag` to the new format.
+
+```powershell
+# Old
+New-AzureRmResourceGroup -Name $resourceGroupName -Location -location -Tags @{ Name = "testtag"; Value = "testval" }
+
+# New
+New-AzureRmResourceGroup -Name $resourceGroupName -Location -location -Tag @{ testtag = "testval" }
+```
+
+<br>
+
+## Breaking changes to Storage cmdlets
+
+The following cmdlets were affected this release:
+
+**Get-AzureRmStorageAccountKey**
+- The cmdlet now returns a list of keys, rather than an object with properties for each key
+
+```powershell
+# Old
+$key = (Get-AzureRmStorageAccountKey -ResourceGroupName $resourceGroupName -Name $accountName).Key1
+
+# New
+$key = (Get-AzureRmStorageAccountKey -ResourceGroupName $resourceGroupName -Name $accountName)[0].Value
+```
+
+**New-AzureRmStorageAccountKey**
+- `StorageAccountRegenerateKeyResponse` field in output of this cmdlet is renamed to `StorageAccountListKeysResults`, which is now a list of keys rather than an object with properties for each key
+
+```powershell
+# Old
+$key = (New-AzureRmStorageAccountKey -ResourceGroupName $resourceGroupName -Name $accountName).StorageAccountKeys.Key1
+
+# New
+$key = (New-AzureRmStorageAccountKey -ResourceGroupName $resourceGroupName -Name $accountName).Keys[0].Value
+```
+
+**New/Get/Set-AzureRmStorageAccount**
+- `AccountType` field in output of this cmdlet is renamed to `Sku.Name`
+- Output type for PrimaryEndpoints/Secondary endpoints blob/table/queue/file changed from `Uri` to `String`
+
+```powershell
+# Old
+$accountType = (Get-AzureRmStorageAccount -ResourceGroupName $resourceGroupName -Name $accountName).AccountType
+
+# New
+$accountType = (Get-AzureRmStorageAccount -ResourceGroupName $resourceGroupName -Name $accountName).Sku.Name
+```
+
+```powershell
+# Old 
+$blobEndpoint = (Get-AzureRmStorageAccount -ResourceGroupName $resourceGroupName -Name $accountName).PrimaryEndpoints.Blob.ToString()
+$blobEndpoint = (Get-AzureRmStorageAccount -ResourceGroupName $resourceGroupName -Name $accountName).PrimaryEndpoints.Blob.AbsolutePath
+
+# New
+$blobEndpoint = (Get-AzureRmStorageAccount -ResourceGroupName $resourceGroupName -Name $accountName).PrimaryEndpoints.Blob.ToString()
+$blobEndpoint = (Get-AzureRmStorageAccount -ResourceGroupName $resourceGroupName -Name $accountName).PrimaryEndpoints.Blob
+```
+
+<br>
+
+## Breaking changes to AD cmdlets
+
+The following cmdlets were affected this release:
+
+**Get-AzureRMADServicePrincipal**
+- `ServicePrincipalName` field in output of this cmdlet is renamed to `ServicePrincipalNames` and is now a collection. It now displays `ApplicationId` also as one of the SPN, along with the identifierUri.
+
+```powershell
+# Old
+$servicePrincipals = Get-AzureRmADServicePrincipal -SearchString $displayName
+$spn = $servicePrincipals[0].ServicePrincipalName
+
+# New
+$servicePrincipals = Get-AzureRmADServicePrincipal -SearchString $displayName
+$spn = $servicePrincipals[0].ServicePrincipalNames[0]
+```
+
+**Get-AzureRmADApplication**
+- Parameter `ApplicationObjectId` is renamed to `ObjectId`.
+- In output of this cmdlet, `ApplicationObjectId` is renamed to `ObjectId`.
+
+```powershell
+# Old
+$app = Get-AzureRmADApplication -ApplicationObjectId $applicationObjectId
+$objectId = $app.ApplicationObjectId
+
+# New
+$app = Get-AzureRmADApplication -ObjectId $objectId
+$objectId = $app.ObjectId
+```
+
+**Remove-AzureRmADApplication**
+- Parameter `ApplicationObjectId` is renamed to `ObjectId`.
+
+```powershell
+# Old
+$app = Remove-AzureRmADApplication -ApplicationObjectId $applicationObjectId -Force
+
+# New
+$app = Remove-AzureRmADApplication -ObjectId $objectId -Force
+```
+
+**New-AzureRmADApplication**
+- In output of this cmdlet, `ApplicationObjectId` is renamed to `ObjectId`.
+- `KeyValue`, `KeyUsage`, `KeyType` parameters are removed.
+
+```powershell
+# Old
+$app = New-AzureRmADApplication -DisplayName $displayName -HomePage $homePage -IdentifierUris $identifierUris -KeyValue $kv -KeyType $kt -KeyUsage $ku
+$id = $app.ApplicationObjectId
+
+# New
+$app = New-AzureRmADApplication -DisplayName $displayName -HomePage $homePage -IdentifierUris $identifierUris
+$id = $app.ObjectId
+New-AzureRmADAppCredential -ObjectId $id -Password $kv
+```
+
+**Get-AzureRmADGroup**
+- `Mail` field is removed from the output.
+
+**Get-AzureRmADUser**
+- `Mail` field is removed from the output.
+
+**New-AzureRmADServicePrincipal**
+- Removed `DisableAccount` parameter.
+
+```powershell
+# Old
+$servicePrincipal = New-AzureRmADServicePrincipal -DisplayName $displayName -Password $password -DisableAccount true
+
+# New
+$servicePrincipal = New-AzureRmADServicePrincipal -DisplayName $displayName -Password $password
+Remove-AzureRmADServicePrincipal -ObjectId $servicePrincipal.ObjectId
+```