Resolve review feedback, add document for installing modules, other minor changes

cormacpayne · cormacpayne · commit 0975654c9bb4 · 2019-03-14T18:25:54.000-07:00
diff --git a/README.md b/README.md
@@ -162,8 +162,8 @@ _This project has adopted the [Microsoft Open Source Code of Conduct][CodeOfCond
 
 [Contributing]: CONTRIBUTING.md
 
-[AzureIcon]: documentation/MicrosoftAzure-32px.png
-[PowershellIcon]: documentation/MicrosoftPowerShellCore-32px.png
+[AzureIcon]: documentation/images/MicrosoftAzure-32px.png
+[PowershellIcon]: documentation/images/MicrosoftPowerShellCore-32px.png
 [AzurePowerShelModules]: documentation/azure-powershell-modules.md
 [DeveloperGuide]: documentation/development-docs/azure-powershell-developer-guide.md
 
@@ -186,12 +186,12 @@ _This project has adopted the [Microsoft Open Source Code of Conduct][CodeOfCond
 [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
+[InstallationGuide]: https://docs.microsoft.com/en-us/powershell/azure/install-az-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
+[ConnectAzAccount]: https://docs.microsoft.com/en-us/powershell/module/az.accounts/connect-azaccount
+[GetAzContext]: https://docs.microsoft.com/en-us/powershell/module/az.accounts/get-azcontext
+[GetAzSubscription]: https://docs.microsoft.com/en-us/powershell/module/az.accounts/get-azsubscription
+[SetAzContext]: https://docs.microsoft.com/en-us/powershell/module/az.accounts/set-azcontext
+[SendFeedback]: https://docs.microsoft.com/en-us/powershell/module/az.accounts/send-feedback
diff --git a/documentation/development-docs/design-guidelines/README.md b/documentation/development-docs/design-guidelines/README.md
@@ -24,11 +24,10 @@ In this folder, you will find best practices and design guidelines for different
 - [Piping Best Practices](./piping-best-practices.md)
     - [Piping in PowerShell](./piping-best-practices.md#piping-in-powershell)
         - [Understanding Piping](./piping-best-practices.md#understanding-piping)
-        - [More Information](./piping-best-practices.md#more-information)
     - [Piping in Azure PowerShell](./piping-best-practices.md#piping-in-azure-powershell)
         - [Using the `-InputObject` Parameter](./piping-best-practices.md#using-the-inputobject-parameter)
         - [Using the `-ResourceId` Parameter](./piping-best-practices.md#using-the-resourceid-parameter)
-        - [Summary](./piping-best-practices.md#summary)
+        - [Full examples](./piping-best-practices.md#full-examples)
 - [`ShouldProcess` and `ConfirmImpact`](./should-process-confirm-impact.md)
     - [`ShouldProcess`](./should-process-confirm-impact.md#shouldprocess)
     - [`ConfirmImpact`](./should-process-confirm-impact.md#confirmimpact)
diff --git a/documentation/development-docs/design-guidelines/piping-best-practices.md b/documentation/development-docs/design-guidelines/piping-best-practices.md
diff --git a/documentation/development-docs/design-guidelines/should-process-confirm-impact.md b/documentation/development-docs/design-guidelines/should-process-confirm-impact.md
@@ -24,6 +24,8 @@ public class RemoveFoo
 }
 ```
 
+Please see the example cmdlets found in our [`examples`](../examples) folder for additional implementations of `ShouldProcess`.
+
 By default, `ShouldProcess` interacts with the cmdlet `ConfirmImpact` and the user's `$ConfirmPreference` setting to decide whether to prompt the user before continuing cmdlet processing. The `$ConfirmPreference` determines the level at which confirmation automatically occurs, and no prompt is shown. If the `ConfirmImpact` specified in a cmdlet is at or below the level of `$ConfirmPreference`, then processing occurs automatically without displaying a prompt. Since both `ConfirmImpact` and `$ConfirmPreference` are set by default to `Medium`, this means that, by default, no confirmation prompt is shown and the cmdlet executes normally.
 
 PowerShell has several tools that allow users to explore and control what happens during execution of cmdlets, and this change in implementation allows them to use these tools.
diff --git a/documentation/development-docs/examples/get-cmdlet-example.md b/documentation/development-docs/examples/get-cmdlet-example.md
@@ -1,5 +1,7 @@
 ## `Get-*` cmdlet example
 
+_Note_: for the below examples, the string "TopLevelResource" would be replaced with the name of your top-level resource (_e.g._, "VirtualMachine", "VirtualNetwork", "SqlServer"), and the string "ChildResource" would be replaced with the name of your child resource (_e.g._, "VirtualMachineExtension", "VirtualNetworkPeering", "SqlDatabase")
+
 ### Top-level resource
 
 All top-level resources should have a `Get-*` cmdlet that allows users to list the resources in their subscription or a resource group, as well as get a specific resource. In addition, users should be able to provide the resource id of the resource they want to get, and the cmdlet will parse the string to get the necessary identity information.
diff --git a/documentation/development-docs/examples/new-cmdlet-example.md b/documentation/development-docs/examples/new-cmdlet-example.md
@@ -1,5 +1,7 @@
 ## `New-*` cmdlet example
 
+_Note_: for the below examples, the string "TopLevelResource" would be replaced with the name of your top-level resource (_e.g._, "VirtualMachine", "VirtualNetwork", "SqlServer"), and the string "ChildResource" would be replaced with the name of your child resource (_e.g._, "VirtualMachineExtension", "VirtualNetworkPeering", "SqlDatabase")
+
 ### Top-level resource
 
 All top-level resources should have a `New-*` cmdlet that allows users to create a resource with given properties. Properties that are required by the API should be mandatory parameters, and in the case where different combinations of properties are needed depending on a provided value (_e.g._, Windows and Linux VMs have different properties), multiple parameter sets should be used. This cmdlet should implement `SupportsShouldProcess` to allow users to provide the `-WhatIf` parameter and see what the result of executing the cmdlet is without the resource actually being created.
diff --git a/documentation/development-docs/examples/remove-cmdlet-example.md b/documentation/development-docs/examples/remove-cmdlet-example.md
@@ -1,5 +1,7 @@
 ## `Remove-*` cmdlet example
 
+_Note_: for the below examples, the string "TopLevelResource" would be replaced with the name of your top-level resource (_e.g._, "VirtualMachine", "VirtualNetwork", "SqlServer"), and the string "ChildResource" would be replaced with the name of your child resource (_e.g._, "VirtualMachineExtension", "VirtualNetworkPeering", "SqlDatabase")
+
 ### Top-level resource
 
 All top-level resources should have a `Remove-*` cmdlet that allows users to delete a specific resource. The user can delete a resource by providing all identity properties, the resource id, or the object representation of the resource. This cmdlet should implement `SupportsShouldProcess` to allow users to provide the `-WhatIf` parameter and see what the result of executing the cmdlet is without the resource actually being deleted. This cmdlet should also implement the [`-PassThru`](../design-guidelines/cmdlet-best-practices.md#returning-no-output) parameter, which allows the user to receive output when no output would normally be provided.
diff --git a/documentation/development-docs/examples/set-cmdlet-example.md b/documentation/development-docs/examples/set-cmdlet-example.md
@@ -1,5 +1,7 @@
 ## `Set-*` cmdlet example
 
+_Note_: for the below examples, the string "TopLevelResource" would be replaced with the name of your top-level resource (_e.g._, "VirtualMachine", "VirtualNetwork", "SqlServer"), and the string "ChildResource" would be replaced with the name of your child resource (_e.g._, "VirtualMachineExtension", "VirtualNetworkPeering", "SqlDatabase")
+
 ### Top-level resource
 
 All top-level resources should have a `Set-*` cmdlet that allows users to update an existing resource _if the API follows `PUT` semantics_. If the API supports `PATCH` semantics, then the cmdlet should be `Update-*` (see below). The user can update an existing resource by providing all identity properties, the resource id, or the object representation of the resource. Similar to the `New-*` cmdlet, properties that are required by the API should be mandatory parameters, and in the case where different combinations of properties are needed depending on a provided value (_e.g._, Windows and Linux VMs have different properties), multiple parameter sets should be used. This cmdlet should implement `SupportsShouldProcess` to allow users to provide the `-WhatIf` parameter and see what the result of executing the cmdlet is without the resource actually being updated.
diff --git a/documentation/development-docs/examples/update-cmdlet-example.md b/documentation/development-docs/examples/update-cmdlet-example.md
@@ -1,5 +1,7 @@
 ## `Update-*` cmdlet example
 
+_Note_: for the below examples, the string "TopLevelResource" would be replaced with the name of your top-level resource (_e.g._, "VirtualMachine", "VirtualNetwork", "SqlServer"), and the string "ChildResource" would be replaced with the name of your child resource (_e.g._, "VirtualMachineExtension", "VirtualNetworkPeering", "SqlDatabase")
+
 ### Top-level resource
 
 All top-level resources should have an `Update-*` cmdlet that allows users to update an existing resource _if the API follows `PATCH` semantics_. If the API supports `PUT` semantics, then the cmdlet should be `Set-*` (see above). The user can update an existing resource by providing all identity properties, the resource id, or the object representation of the resource. Similar to the `New-*` cmdlet, properties that are required by the API should be mandatory parameters, and in the case where different combinations of properties are needed depending on a provided value (_e.g._, Windows and Linux VMs have different properties), multiple parameter sets should be used. This cmdlet should implement `SupportsShouldProcess` to allow users to provide the `-WhatIf` parameter and see what the result of executing the cmdlet is without the resource actually being updated.
diff --git a/documentation/images/MicrosoftAzure-32px.png b/documentation/images/MicrosoftAzure-32px.png
diff --git a/documentation/images/MicrosoftPowerShellCore-32px.png b/documentation/images/MicrosoftPowerShellCore-32px.png
diff --git a/documentation/installing-az-modules.md b/documentation/installing-az-modules.md
@@ -0,0 +1,69 @@
+# Installing `Az` Modules
+
+## Overview
+
+By default, modules are installed from the [PowerShell Gallery](https://www.powershellgallery.com/), which is the central repository for accessing published PowerShell modules (equivalent to NuGet for .NET, npm for JavaScript, etc.). With the [`Install-Module`](https://docs.microsoft.com/en-us/powershell/module/powershellget/install-module) cmdlet, users can specify which modules they want to install; in addition, users can provide the `-Repository` parameter to specify which repository they want to install modules from (if this parameter isn't provided, then the cmdlet defaults to using PowerShell Gallery).
+
+## Removing Modules
+
+In some cases, existing `Az` modules will need to be removed before a new version can be installed. Since the `Uninstall-Module` cmdlet does not currently remove modules and their dependencies, users will need to manually delete the folders where the modules were installed to.
+
+To figure out if you have any `Az` modules currently installed, as well as the location they are found, use the following command:
+
+```
+Get-Module -Name Az* -ListAvailable
+```
+
+This command will list all modules installed on your machine that are found in your `$env:PSModulePath`. Deleting the corresponding `Az.*` folders in the file explorer will remove these modules from your machine.
+
+## Registering Repositories
+
+In some cases, users will need to install modules from a different repository than the PowerShell Gallery -- this can be a new endpoint, or even a local folder containing `.nupkg` files. In either case, the [`Register-PSRepository`](https://docs.microsoft.com/en-us/powershell/module/powershellget/register-psrepository) cmdlet should be used to create a new local repository that can be used to install modules from.
+
+Below is an example of registering a new repository from a local folder containing `.nupkg` files:
+
+```
+Register-PSRepository -Name "{{repository_name}}" -SourceLocation "{{folder_with_nupkg_files}}" -PackageManagementProvider NuGet -Installation
+```
+
+## Installing Modules
+
+To install a module from the PowerShell Gallery, run the following command:
+
+```
+Install-Module -Name "{{module_name}}"
+```
+
+To install a module from a specific repository, run the following command:
+
+```
+Install-Module -Name "{{module_name}}" -Repository "{{repository_name}}"
+```
+
+### Installing `Az` Modules
+
+To install the latest stable `Az` modules from the PowerShell Gallery, run the following command:
+
+```
+Install-Module -Name Az
+```
+
+To install a specific `Az` module from the PowerShell Gallery, run the following command:
+
+```
+Install-Module -Name Az.{{service}}
+```
+
+To install a preview version of a specific `Az` module, run the following command:
+
+```
+Install-Module -Name Az.{{service}} -RequiredVersion {{version}} -AllowPrelease
+```
+
+_Note_: to install preview versions of modules, version 1.6.0 or greater of the `PowerShellGet` module will be needed. Users can run the following command to get the latest version of this module:
+
+```
+Install-Module -Name PowerShellGet -Force
+```
+
+Full documentation around installing the `Az` module can be found in the [_Install the Azure PowerShell module_](https://docs.microsoft.com/en-us/powershell/azure/install-az-ps) article.

Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,8 @@ public class RemoveFoo`
`24`	`24`	`}`
`25`	`25`	```
`26`	`26`
	`27`	+Please see the example cmdlets found in our [`examples`](../examples) folder for additional implementations of `ShouldProcess`.
	`28`	`+`
`27`	`29`	By default, `ShouldProcess` interacts with the cmdlet `ConfirmImpact` and the user's `$ConfirmPreference` setting to decide whether to prompt the user before continuing cmdlet processing. The `$ConfirmPreference` determines the level at which confirmation automatically occurs, and no prompt is shown. If the `ConfirmImpact` specified in a cmdlet is at or below the level of `$ConfirmPreference`, then processing occurs automatically without displaying a prompt. Since both `ConfirmImpact` and `$ConfirmPreference` are set by default to `Medium`, this means that, by default, no confirmation prompt is shown and the cmdlet executes normally.
`28`	`30`
`29`	`31`	`PowerShell has several tools that allow users to explore and control what happens during execution of cmdlets, and this change in implementation allows them to use these tools.`