Improve 'migration' articles #1070
Conversation
sptramer
changed the title
|
@dcaro @sdwheeler @sphibbs Requesting review since this is a fairly serious set of changes I want a set of second eyes on to ensure that it's correct and properly deep-links users through the migration process. All feedback is welcome. |
|
Docs Build status updates of commit 764a5d1: 🕙 Full build: the average full build time is 33 min(s) 30 sec(s), this is based on the last 90 build(s) for this repository. |
|
Docs Build status updates of commit 764a5d1: ✅ Validation status: passed
docs-conceptual/azps-2.0.0/migrate-az-1.0.0.md
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
Docs Build status updates of commit 425879e: 🕙 Full build: the average full build time is 33 min(s) 26 sec(s), this is based on the last 91 build(s) for this repository. |
|
Docs Build status updates of commit 425879e: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
Docs Build status updates of commit 5adc751: 🕙 Full build: the average full build time is 33 min(s) 23 sec(s), this is based on the last 92 build(s) for this repository. |
|
Docs Build status updates of commit 5adc751: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
|
||
| This document describes the changes between the 6.x versions of AzureRM and Az version 1.0.0. | ||
| For general advice on getting started with a migration from AzureRM to Az, see [Start migration from | ||
| AzureRM to Az](migrate-from-azurerm-to-az.md). | ||
|
|
||
| ## Table of Contents |
There was a problem hiding this comment.
Style-wise, we do not do TOCs within documents. All H2 headers are automatically added to the right-hand Nav pane.
There was a problem hiding this comment.
Normally I would agree, but the RHS gutter isn't appropriate for an article like this, which needs many easily navigable subheadings with long titles. I think release notes are a special case that aren't handled particularly well by the azure-docs infrastructure and guidelines.
| #### Migrating #Requires Statements | ||
| Scripts that use #Requires to declare a dependency on AzureRM modules should be updated to use the new module names | ||
| ```powershell | ||
| The changes in module names mean that any script that uses ```#Requires``` or ```Import-Module``` to load specific modules will need to be changed to use the new module instead. For modules where the cmdlet suffix has not changed, |
There was a problem hiding this comment.
Inline code fencing should use a single backtick. For example:
`#Requires` or `Import-Module`| The changes in module names mean that any script that uses ```#Requires``` or ```Import-Module``` to load specific modules will need to be changed to use the new module instead. | ||
| The module names have changed from `AzureRM.*` to `Az.*`, except for the following modules: | ||
|
|
||
| | AzureRM module | Az module | Cmdlet suffix changed? | |
There was a problem hiding this comment.
It's not clear to me what a "suffix" is in this context. Do you mean the cmdlet Noun? Suffix is not a term that has been used in PowerShell. So this should be changed or defined.
There was a problem hiding this comment.
This was meant to represent things like where the module name was part of a cmdlet name, and whether or not that changed along with the module name (most cmdlets didn't) but you're right that it's too confusing. Removing.
|
|
||
| ```powershell | ||
| ```azurepowershell-interactive |
There was a problem hiding this comment.
This is not an executable statement. It is a member of a hash table in the manifest file. So the code fence type should not be interactive. It should be "powershell".
|
|
||
| ```powershell | ||
| ```azurepowershell-interactive |
There was a problem hiding this comment.
This is not an executable statement. It is a member of a hash table in the manifest file. So the code fence type should not be interactive. It should be "powershell".
|
|
||
| ### Windows PowerShell 5.1 and .NET 4.7.2 | ||
| - Using Az with Windows PowerShell 5.1 requires the installation of .NET 4.7.2. However, using Az with PowerShell Core does not require .NET 4.7.2. | ||
|
|
||
| Using Az with Windows PowerShell 5.1 requires the installation of .NET 4.7.2. However, using Az with PowerShell Core does not require .NET 4.7.2. |
There was a problem hiding this comment.
".NET Framework 4.7.2" not ".NET 4.7.2"
|
|
||
| ### Default Device Code login instead of Web Browser prompt | ||
| - Due to changes in the authentication flow for .NET Standard, we are using device login as the default login flow during interactive login. Web browser based login will be re-introduced for Windows PowerShell 5.1 as the default in the 1/15/2019 release. At that time, users will be able to choose device login using a Switch parameter. | ||
| Due to changes in the authentication flow for .NET Standard, we are temporarily removing user login via PSCredential. This capability will be re-introduced in the 1/15/2019 release for Windows PowerShell 5.1. This is discussed in detail in [this GitHub issue.](https://github.com/Azure/azure-powershell/issues/7430) |
There was a problem hiding this comment.
We are past this date. Is this still a problem? I am not aware of 1/15/2019 release of PowerShell 5.1. Or do you mean the release of Az PowerShell and not Windows PowerShell 5.1?
There was a problem hiding this comment.
@dcaro I was wondering this myself. The github issues are a labrynth here, I clicked through something like 4 layers of them and still didn't find out whether or not this has been fixed.
|
|
||
| ### Default device code login instead of web browser prompt | ||
|
|
||
| Due to changes in the authentication flow for .NET Standard, we are using device login as the default login flow during interactive login. Web browser based login will be re-introduced for Windows PowerShell 5.1 as the default in the 1/15/2019 release. At that time, users will be able to choose device login using a Switch parameter. |
There was a problem hiding this comment.
1/15/2019 release of what? Not clear here. And is this still relevant since we are past that date.
| - New-AzureRmApiManagementHostnameConfiguration | ||
| - Set-AzureRmApiManagementHostnames | ||
| - Update-AzureRmApiManagementDeployment | ||
| - Import-AzureRmApiManagementHostnameCertificate | ||
| - Use **Set-AzApiManagement** cmdlet to set these properites instead | ||
| - Following properties were removed | ||
| - Removed the following properties: | ||
| - Removed property `PortalHostnameConfiguration`, `ProxyHostnameConfiguration`, `ManagementHostnameConfiguration` and `ScmHostnameConfiguration` of type `PsApiManagementHostnameConfiguration` from `PsApiManagementContext`. Instead use `PortalCustomHostnameConfiguration`, `ProxyCustomHostnameConfiguration`, `ManagementCustomHostnameConfiguration` and `ScmCustomHostnameConfiguration` of type `PsApiManagementCustomHostNameConfiguration`. |
There was a problem hiding this comment.
The style guide we have for PowerShell says that properties, class names, type names, and cmdlet parameters should be in bold and cmdlet names should be in backticks (code fences).
There was a problem hiding this comment.
I've taken a general task to fix the AzPS docs to conform to this style guide and will update the entire docset at one time. I'm assuming that the reference already follows these guidelines?
There was a problem hiding this comment.
Read the whole contributor guide in that folder. There are many aspects for how we format the PowerShell docs. Let me know if you have any questions. It is a living document. We add or change things as necessary. But this has help drive consistency in my docset.
|
Docs Build status updates of commit cb1bc55: 🕙 Full build: the average full build time is 33 min(s) 21 sec(s), this is based on the last 93 build(s) for this repository. |
|
Docs Build status updates of commit cb1bc55: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
- Copyedit 'breaking changes' list - Edit existing 'migration' article to improve language and deep links to breaking changes - Better referencing of migration articles in the 'new module' article
|
Docs Build status updates of commit 2bf52f8: 🕙 Full build: the average full build time is 32 min(s) 46 sec(s), this is based on the last 99 build(s) for this repository. |
|
Docs Build status updates of commit 2bf52f8: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
Docs Build status updates of commit 52739f9: 🕙 Full build: the average full build time is 32 min(s) 46 sec(s), this is based on the last 100 build(s) for this repository. |
|
Docs Build status updates of commit 52739f9: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
|
Docs Build status updates of commit 893703e: 🕙 Full build: the average full build time is 32 min(s) 38 sec(s), this is based on the last 103 build(s) for this repository. |
|
Docs Build status updates of commit 893703e: ✅ Validation status: passed
For more details, please refer to the build report. Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report. |
No description provided.