Updated Readme and module documents to be accurate for Az.

Author: MiYanni

README.md

@@ -1,176 +1,197 @@
 <meta name="google-site-verification" content="tZgbB2s-hTI0IePQQRCjHqL_Vf0j_XJmehXAHJerrn4" />
 
-# Microsoft Azure PowerShell
+# ![AzureIcon] ![PowershellIcon] Microsoft Azure PowerShell
 
-This repository contains a set of PowerShell cmdlets for developers and administrators to develop, deploy and manage Microsoft Azure applications.
+This repository contains PowerShell cmdlets for developers and administrators to develop, deploy, and manage Microsoft Azure applications.
 
-Take a test run now from Azure Cloud Shell! 
-
-[![](https://shell.azure.com/images/launchcloudshell.png "Launch Azure Cloud Shell")](https://shell.azure.com/powershell) 
+Try it out in Azure Cloud Shell!
 
+[![CloudShellIcon]][CloudShell]
 
 ## Modules
+Below is a table containing our Azure PowerShell rollup module.
 
-Below is a table containing the various Azure PowerShell rollup modules found in this repository. For a full list of modules found in this repository, please see the [Azure PowerShell Modules](documentation/azure-powershell-modules.md) page.
+Description                           | Module Name                             | PowerShell Gallery Link
+------------------------------------- | --------------------------------------- | -----------------------
+Azure PowerShell                      | `Az`                                    | [![Az]][AzGallery]
 
-| Description                                                     | Module Name       | PowerShell Gallery Link |
-| --------------------------------------------------------------- | ----------------- | ----------------------- |
-| Rollup Module for ARM Cmdlets                                   | `AzureRM`         | [![AzureRM](https://img.shields.io/powershellgallery/v/AzureRM.svg?style=flat-square&label=AzureRM)](https://www.powershellgallery.com/packages/AzureRM/) |
-| Rollup Module for .NET Standard cmdlets                         | `Az` | [![Az](https://img.shields.io/powershellgallery/v/Az.svg?style=flat-square&label=Az)](https://www.powershellgallery.com/packages/Az/) |
-| Rollup Module for Administrative Modules in Azure Stack         | `AzureStack`      | [![AzureStack](https://img.shields.io/powershellgallery/v/AzureStack.svg?style=flat-square&label=AzureStack)](https://www.powershellgallery.com/packages/AzureStack/) |
-| Rollup Module for Service Management Cmdlets                  | `Azure`           | [![Azure](https://img.shields.io/powershellgallery/v/Azure.svg?style=flat-square&label=Azure)](https://www.powershellgallery.com/packages/Azure/) |
+For a full list of modules found in this repository, please see the [Azure PowerShell Modules][AzurePowerShelModules] document.
 
 ## Installation
 
-For more detailed instructions on installing Azure PowerShell, please refer to the [installation guide](https://docs.microsoft.com/en-us/powershell/azure/install-azurerm-ps).
-
 ### PowerShell Gallery
 
-Run the following command in an elevated PowerShell session to install the rollup module for Azure Resource Manager cmdlets:
-
-```powershell
-Install-Module -Name AzureRM
-```
-
-Run the following command in an elevated PowerShell session to install the new 'Az' module for ResourceManager cmdlets. This module runs on PowerShell 5.1 (with .Net Framework 4.7.2) ,  or PowerShell Core, and replaces AzureRM.  You should not install this module side-by-side with AzureRM:
+Run the following command in an elevated PowerShell session to install the rollup module for Azure PowerShell cmdlets:
 
 ```powershell
 Install-Module -Name Az
 ```
 
-To install the module containing the legacy RDFE cmdlets, run the following command in an elevated PowerShell session:
+This module runs on Windows PowerShell with [.NET Framework 4.7.2][DotNetFramework] or greater, or [PowerShell Core][PowerShellCore]. The Az module replaces AzureRM. You should not install Az side-by-side with AzureRM.
 
-```powershell
-Install-Module -Name Azure
-```
-
-If you have an earlier version of the Azure PowerShell modules installed from the PowerShell Gallery and would like to update to the latest version, run the following commands in an elevated PowerShell session. Update-Module installs the new version side-by-side with the old version. It does not remove the old version.
+If you have an earlier version of the Azure PowerShell modules installed from the PowerShell Gallery and would like to update to the latest version, run the following commands in an elevated PowerShell session:
 
 ```powershell
-# Update to the latest version of AzureRM
-Update-Module -Name AzureRM
-
-# Update to the latest version of Az
 Update-Module -Name Az
-
-# Update to the latest version of Azure
-Update-Module -Name Azure
 ```
 
-### Web Platform Installer
+`Update-Module` installs the new version side-by-side with previous versions. It does not uninstall the previous versions.
 
-Download and install the [Microsoft Web Platform Installer](https://www.microsoft.com/web/downloads/platform.aspx). Once installed, open the program and search for _Microsoft Azure PowerShell_. Click the _Add_ button followed by the _Install_ button at the bottom to begin the installation process.
+For detailed instructions on installing Azure PowerShell, please refer to the [installation guide][InstallationGuide].
 
 ## Usage
 
-For more detailed instructions on using Azure PowerShell, please refer to the [getting started guide](https://docs.microsoft.com/en-us/powershell/azure/get-started-azureps).
-
-### Log in to Azure
+### Log into Azure
 
-To connect to Azure, use the [`Connect-AzureRmAccount`](https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/connect-azurermaccount) cmdlet.
+To connect to Azure, use the [Connect-AzAccount][ConnectAzAccount] cmdlet:
 
 ```powershell
-# Interactive login - you will get a dialog box asking for your Azure credentials
-Connect-AzureRmAccount
+# Device Code login - Provides a link to sign into Azure via your web browser
+Connect-AzAccount
 
-# Non-interactive login - you will need to use a service principal
-Connect-AzureRmAccount -ServicePrincipal -ApplicationId "http://my-app" -Credential $PSCredential -TenantId $TenantId
+# Service Principal login - Use a previously created service principal to log in
+Connect-AzAccount -ServicePrincipal -ApplicationId 'http://my-app' -Credential $PSCredential -TenantId $TenantId
 ```
 
 To log into a specific cloud (_AzureChinaCloud_, _AzureCloud_, _AzureGermanCloud_, _AzureUSGovernment_), use the `Environment` parameter:
 
 ```powershell
-# Log into a specific cloud - in this case, the Azure China cloud
-Connect-AzureRmAccount -Environment AzureChinaCloud
+# Specific cloud login - Logs into the Azure China cloud
+Connect-AzAccount -Environment AzureChinaCloud
 ```
 
-### Getting and setting your session context
+### Getting and setting your Azure PowerShell session context
 
-To view the context you are using in the current session, which contains the subscription and tenant, use the [`Get-AzureRmContext`](https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/get-azurermcontext) cmdlet:
+A session context persists login information across Azure PowerShell modules and PowerShell instances. To view the context you are using in the current session, which contains the subscription and tenant, use the [Get-AzContext][GetAzContext] cmdlet:
 
 ```powershell
-# Get the context you are currently using
-Get-AzureRmContext
+# Gets the Azure PowerShell context for the current PowerShell session
+Get-AzContext
 
-# List all available contexts in the current session
-Get-AzureRmContext -ListAvailable
+# Lists all available Azure PowerShell contexts in the current PowerShell session
+Get-AzContext -ListAvailable
 ```
 
-To get the subscriptions in a tenant, use the [`Get-AzureRmSubscription`](https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/get-azurermsubscription) cmdlet:
+To get the subscriptions in a tenant, use the [Get-AzSubscription][GetAzSubscription] cmdlet:
 
 ```powershell
-# Get all of the subscriptions in your current tenant
-Get-AzureRmSubscription
+# Get all of the Azure subscriptions in your current Azure tenant
+Get-AzSubscription
 
-# Get all of the subscriptions in a specific tenant
-Get-AzureRmSubscription -TenantId $TenantId
+# Get all of the Azure subscriptions in a specific Azure tenant
+Get-AzSubscription -TenantId $TenantId
 ```
 
-To change the subscription that you are using for your current context, use the [`Set-AzureRmContext`]() cmdlet:
+To change the subscription that you are using for your current context, use the [Set-AzContext][SetAzContext] cmdlet:
 
 ```powershell
-# Set the context to a specific subscription
-Set-AzureRmContext -Subscription $SubscriptionName -Name "MyContext"
+# Set the Azure PowerShell context to a specific Azure subscription
+Set-AzContext -Subscription $SubscriptionName -Name 'MyContext'
 
-# Set the context using piping
-Get-AzureRmSubscription -SubscriptionName $SubscriptionName | Set-AzureRmContext -Name "MyContext"
+# Set the Azure PowerShell context using piping
+Get-AzSubscription -SubscriptionName $SubscriptionName | Set-AzureRmContext -Name 'MyContext'
 ```
 
+For details on Azure PowerShell contexts, see our [persisted credentials guide][PersistedCredentialsGuide].
+
 ### Discovering cmdlets
 
 Use the `Get-Command` cmdlet to discover cmdlets within a specific module, or cmdlets that follow a specific search pattern:
 
 ```powershell
-# View all cmdlets in the AzureRM.Profile module
-Get-Command -Module AzureRM.Profile
+# List all cmdlets in the Az.Accounts module
+Get-Command -Module Az.Accounts
 
-# View all cmdlets that contain "VirtualNetwork"
-Get-Command -Name "*VirtualNetwork*"
+# List all cmdlets that contain VirtualNetwork
+Get-Command -Name '*VirtualNetwork*'
 
-# View all cmdlets that contain "VM" in the AzureRM.Compute module
-Get-Command -Module AzureRM.Compute -Name "*VM*"
+# List all cmdlets that contain VM in the Az.Compute module
+Get-Command -Module Az.Compute -Name '*VM*'
 ```
 
 ### Cmdlet help and examples
 
 To view the help content for a cmdlet, use the `Get-Help` cmdlet:
 
 ```powershell
-# View the basic help content for Get-AzureRmSubscription
-Get-Help -Name Get-AzureRmSubscription
+# View the basic help content for Get-AzSubscription
+Get-Help -Name Get-AzSubscription
 
-# View the examples for Get-AzureRmSubscription
-Get-Help -Name Get-AzureRmSubscription -Examples
+# View the examples for Get-AzSubscription
+Get-Help -Name Get-AzSubscription -Examples
 
-# View the full help content for Get-AzureRmSubscription
-Get-Help -Name Get-AzureRmSubscription -Full
+# View the full help content for Get-AzSubscription
+Get-Help -Name Get-AzSubscription -Full
 
-# View the help content for Get-AzureRmSubscription on https://docs.microsoft.com
-Get-Help -Name Get-AzureRmSubscription -Online
+# View the help content for Get-AzSubscription on https://docs.microsoft.com
+Get-Help -Name Get-AzSubscription -Online
 ```
 
+For detailed instructions on using Azure PowerShell, please refer to the [getting started guide][GettingStartedGuide].
+
 ## Reporting Issues and Feedback
 
 ### Issues
 
-If you find any bugs when using the Azure PowerShell modules, please file an issue [here](https://github.com/Azure/azure-powershell/issues), making sure to fill out the provided template with the appropriate information.
+If you find any bugs when using the Azure PowerShell modules, please file an issue in our [GitHub issues][GitHubIssues] page. Please fill out the provided template with the appropriate information.
 
-Alternatively, be sure to check out the [Azure Support Community](https://azure.microsoft.com/en-us/support/forums/) if you have trouble with any of the cmdlets or Azure services.
+Alternatively, be sure to check out the [Azure Community Support](https://azure.microsoft.com/en-us/support/community/) if you have issues with the cmdlets or Azure services.
 
 ### Feedback
 
-If there is a feature you would like to see in Azure PowerShell, please use the [`Send-Feedback`](https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/send-feedback) cmdlet, or file an issue [here](https://github.com/Azure/azure-powershell/issues), to send the team direct feedback.
+If there is a feature you would like to see in Azure PowerShell, please use the [Send-Feedback][SendFeedback] cmdlet, or file an issue in our [GitHub issues][GitHubIssues] page to provide the Azure PowerShell team direct feedback.
 
 ## Contribute Code
 
-If you would like to become an active contributor to this project please follow the instructions provided in [Microsoft Azure Projects Contribution Guidelines](https://azure.github.io/guidelines/).
+If you would like to become an active contributor to this project, please follow the instructions provided in [Microsoft Azure Projects Contribution Guidelines][ContributionGuidelines].
 
-More information about contributing to this repo can be found in [CONTRIBUTING md](https://github.com/Azure/azure-powershell/blob/preview/CONTRIBUTING.md) and the [Azure PowerShell Developer Guide](https://github.com/Azure/azure-powershell/blob/preview/documentation/development-docs/azure-powershell-developer-guide.md) folder.
+Additional information about contributing to this repository can be found in the [Contributing][Contributing] document and the [Azure PowerShell Developer Guide][DeveloperGuide] document.
 
 ## Learn More
 
-* [Microsoft Azure Documentation](https://docs.microsoft.com/en-us/azure/)
-* [PowerShell Documentation](https://docs.microsoft.com/en-us/powershell/)
+* [Microsoft Azure Documentation][MicrosoftAzureDocs]
+* [PowerShell Documentation][PowerShellDocs]
 
 ---
-_This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments._
+_This project has adopted the [Microsoft Open Source Code of Conduct][CodeOfConduct]. For more information see the [Code of Conduct FAQ][CodeOfConductFaq] or contact [[email protected]][OpenCodeEmail] with any additional questions or comments._
+
+<!-- References -->
+
+<!-- Local -->
+[GitHubIssues]: https://github.com/Azure/azure-powershell/issues
+
+[Contributing]: CONTRIBUTING.md
+
+[AzureIcon]: documentation/MicrosoftAzure-32px.png
+[PowershellIcon]: documentation/MicrosoftPowerShellCore-32px.png
+[AzurePowerShelModules]: documentation/azure-powershell-modules.md
+[DeveloperGuide]: documentation/development-docs/azure-powershell-developer-guide.md
+
+<!-- External -->
+[Az]: https://img.shields.io/powershellgallery/v/Az.svg?style=flat-square&label=Az
+[AzGallery]: https://www.powershellgallery.com/packages/Az/
+
+[DotNetFramework]: https://dotnet.microsoft.com/download/dotnet-framework-runtime
+[PowerShellCore]: https://github.com/PowerShell/PowerShell/releases/latest
+
+[CloudShell]: https://shell.azure.com/powershell
+[CloudShellIcon]: https://shell.azure.com/images/launchcloudshell.png "Launch Azure Cloud Shell"
+
+[ContributionGuidelines]: https://azure.github.io/guidelines/
+[CodeOfConduct]: https://opensource.microsoft.com/codeofconduct/
+[CodeOfConductFaq]: https://opensource.microsoft.com/codeofconduct/faq/
+[OpenCodeEmail]: mailto:[email protected]
+
+<!-- Docs -->
+[MicrosoftAzureDocs]: https://docs.microsoft.com/en-us/azure/
+[PowerShellDocs]: https://docs.microsoft.com/en-us/powershell/
+
+[InstallationGuide]: https://docs.microsoft.com/en-us/powershell/azure/install-azurerm-ps
+[GettingStartedGuide]: https://docs.microsoft.com/en-us/powershell/azure/get-started-azureps
+[PersistedCredentialsGuide]: https://docs.microsoft.com/en-us/powershell/azure/context-persistence
+
+[ConnectAzAccount]: https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/connect-azurermaccount
+[GetAzContext]: https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/get-azurermcontext
+[GetAzSubscription]: https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/get-azurermsubscription
+[SetAzContext]: https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/set-azurermcontext
+[SendFeedback]: https://docs.microsoft.com/en-us/powershell/module/azurerm.profile/send-feedback