Skip to content

Commit

Permalink
Updated readme as referenced in issue 14021 (#19954)
Browse files Browse the repository at this point in the history 
* Updated readme as referenced in issue 14021

* Reverted table due to formatting issues

Co-authored-by: Mike F. Robbins <[email protected]>
  • Loading branch information
@mikefrobbins
mikefrobbins and mikefrobbins authored Oct 28, 2022
1 parent 76c8995 commit 3c1572d
Showing 1 changed file with 84 additions and 51 deletions.
135 changes: 84 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,51 @@

# ![AzureIcon] ![PowershellIcon] Microsoft Azure PowerShell

This repository contains 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,
administer, and manage Microsoft Azure resources.

Try it out in [Azure Cloud Shell](https://portal.azure.com/#cloudshell)!
The Az PowerShell module is preinstalled in [Azure Cloud Shell][AzureCloudShell].

## Modules
Below is a table containing our Azure PowerShell rollup module.

The following table contains a list of the Azure PowerShell rollup modules.

Description | Module Name | PowerShell Gallery Link
----------------- | ------------ | -----------------------
Azure PowerShell | `Az` | [![Az]][AzGallery]
Azure PowerShell with preview modules | `AzPreview` | [![AzPreview]][AzPreviewGallery]

For a full list of modules found in this repository, please see the [Azure PowerShell Modules][AzurePowerShelModules] document.
For a complete list of the modules found in this repository, see
[Azure PowerShell Modules][AzurePowerShellModules].

## Installation

### PowerShell Gallery

Run the following command in an elevated PowerShell session to install the rollup module for Azure PowerShell cmdlets:
Run the following command in a PowerShell session to install the Az PowerShell module:

```powershell
Install-Module -Name Az
Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force
```

This module runs on Windows PowerShell with [.NET Framework 4.7.2][DotNetFramework] or greater, or [the latest version of PowerShell 7][PowerShellCore]. The `Az` module replaces `AzureRM`. You should not install `Az` side-by-side with `AzureRM`.
[The latest version of PowerShell 7][PowerShellCore] is the recommended version of PowerShell for
use with the Az PowerShell module on all platforms including Windows, Linux, and macOS. This module
also runs on Windows PowerShell 5.1 with [.NET Framework 4.7.2][DotNetFramework] or higher.

The `Az` module replaces `AzureRM`. You should not install `Az` side-by-side with `AzureRM`.

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:
If you have an earlier version of the Azure PowerShell module installed from the PowerShell Gallery
and would like to update to the latest version, run the following command in a PowerShell session:

```powershell
Update-Module -Name Az
Update-Module -Name Az -Scope CurrentUser -Force
```

`Update-Module` installs the new version side-by-side with previous versions. It does not uninstall the previous versions.
`Update-Module` installs the new version side-by-side with previous versions. It does not uninstall
the previous versions.

For detailed instructions on installing Azure PowerShell, please refer to the [installation guide][InstallationGuide].
For more information on installing Azure PowerShell, see the
[installation guide][InstallationGuide].

## Usage

Expand All @@ -45,26 +55,30 @@ For detailed instructions on installing Azure PowerShell, please refer to the [i
To connect to Azure, use the [`Connect-AzAccount`][ConnectAzAccount] cmdlet:

```powershell
# Device Code login - Provides a link to sign into Azure via your web browser
# Opens a new browser window to log into your Azure account.
Connect-AzAccount
# Service Principal login - Use a previously created service principal to log in
Connect-AzAccount -ServicePrincipal -ApplicationId 'http://my-app' -Credential $PSCredential -TenantId $TenantId
# Log in with a previously created service principal. Use the application ID as the username, and the secret as password.
$Credential = Get-Credential
Connect-AzAccount -ServicePrincipal -Credential $Credential -TenantId $TenantId
```

To log into a specific cloud (_AzureChinaCloud_, _AzureCloud_, _AzureUSGovernment_), use the `-Environment` parameter:
To log into a specific cloud (_AzureChinaCloud_, _AzureCloud_, _AzureUSGovernment_), use the
`Environment` parameter:

```powershell
# Specific cloud login - Logs into the Azure China cloud
# Log into a specific cloud, for example the Azure China cloud.
Connect-AzAccount -Environment AzureChinaCloud
```

### Getting and setting your Azure PowerShell session context
### Session context

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:
A session context persists login information across Azure PowerShell modules and PowerShell
instances. Use the [`Get-AzContext`][GetAzContext] cmdlet to view the context you are using in the
current session. The results contain the Azure tenant and subscription.

```powershell
# Gets the Azure PowerShell context for the current PowerShell session
# Get the Azure PowerShell context for the current PowerShell session
Get-AzContext
# Lists all available Azure PowerShell contexts in the current PowerShell session
Expand All @@ -81,7 +95,8 @@ Get-AzSubscription
Get-AzSubscription -TenantId $TenantId
```

To change the subscription that you are using for your current context, use the [`Set-AzContext`][SetAzContext] cmdlet:
To change the subscription that you are using for your current context, use the
[`Set-AzContext`][SetAzContext] cmdlet:

```powershell
# Set the Azure PowerShell context to a specific Azure subscription
Expand All @@ -91,20 +106,21 @@ Set-AzContext -Subscription $SubscriptionName -Name 'MyContext'
Get-AzSubscription -SubscriptionName $SubscriptionName | Set-AzContext -Name 'MyContext'
```

For details on Azure PowerShell contexts, see our [persisted credentials guide][PersistedCredentialsGuide].
For details on Azure PowerShell contexts, see [Azure PowerShell context objects][PersistedCredentialsGuide].

### Discovering cmdlets

Use the `Get-Command` cmdlet to discover cmdlets within a specific module, or cmdlets that follow a specific search pattern:
Use `Get-Command` to discover cmdlets within a specific module, or cmdlets that follow a specific
search pattern:

```powershell
# List all cmdlets in the Az.Accounts module
Get-Command -Module Az.Accounts
# List all cmdlets that contain VirtualNetwork
# List all cmdlets that contain VirtualNetwork in their name
Get-Command -Name '*VirtualNetwork*'
# List all cmdlets that contain VM in the Az.Compute module
# List all cmdlets that contain VM in their name in the Az.Compute module
Get-Command -Module Az.Compute -Name '*VM*'
```

Expand All @@ -113,63 +129,75 @@ Get-Command -Module Az.Compute -Name '*VM*'
To view the help content for a cmdlet, use the `Get-Help` cmdlet:

```powershell
# View the basic help content for Get-AzSubscription
# View basic help information for Get-AzSubscription
Get-Help -Name Get-AzSubscription
# View the examples for Get-AzSubscription
Get-Help -Name Get-AzSubscription -Examples
# View the full help content for Get-AzSubscription
# View the full help for Get-AzSubscription
Get-Help -Name Get-AzSubscription -Full
# View the help content for Get-AzSubscription on https://docs.microsoft.com
# View the online version of the help from https://learn.microsoft.com for Get-AzSubscription
Get-Help -Name Get-AzSubscription -Online
```

For detailed instructions on using Azure PowerShell, please refer to the [getting started guide][GettingStartedGuide].
For detailed instructions on using Azure PowerShell, see 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 in our [GitHub issues][GitHubIssues] page. Please fill out the provided template with the appropriate information.
If you find any bugs when using Azure PowerShell, file an issue in our [GitHub repo][GitHubRepo].
Fill out the issue template with the appropriate information.

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.
Alternatively, see [Azure Community Support][AzureCommunitySupport] if you
have issues with Azure PowerShell or Azure services.

### 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.
If there is a feature you would like to see in Azure PowerShell, use the
[`Send-Feedback`][SendFeedback] cmdlet, or file an issue in our [GitHub repo][GitHubRepo].

## 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][ContributionGuidelines].
If you would like to become a contributor to this project, see the instructions provided in
[Microsoft Azure Projects Contribution Guidelines][ContributionGuidelines].

Additional information about contributing to this repository can be found in the [`CONTRIBUTING.md`][Contributing] document and the [_Azure PowerShell Developer Guide_][DeveloperGuide] document.
Additional information about contributing to this repository can be found in
[`CONTRIBUTING.md`][Contributing] and the [_Azure PowerShell Developer Guide_][DeveloperGuide].

## Telemetry

Azure PowerShell collects telemetry data by default. Microsoft aggregates collected data to identify patterns of usage to identify common issues and to improve the experience of Azure PowerShell. Microsoft Azure PowerShell does not collect any private or personal data.
For example, the usage data helps identify issues such as cmdlets with low success and helps prioritize our work.
While we appreciate the insights this data provides, we also understand that not everyone wants to send usage data. You can disable data collection with the [`Disable-AzDataCollection`](/powershell/module/az.accounts/disable-azdatacollection) cmdlet. You can also read our [privacy statement](https://privacy.microsoft.com/privacystatement) to learn more.
Azure PowerShell collects telemetry data by default. Microsoft aggregates collected data to identify
patterns of usage to identify common issues and to improve the experience of Azure PowerShell.
Microsoft Azure PowerShell does not collect any private or personal data. For example, the usage
data helps identify issues such as cmdlets with low success and helps prioritize our work. While we
appreciate the insights this data provides, we also understand that not everyone wants to send usage
data. You can disable data collection with the
[`Disable-AzDataCollection`][DisableAzDataCollection] cmdlet. To learn more, see our
[privacy statement][PrivacyStatement].

## Learn More

* [Microsoft Azure Documentation][MicrosoftAzureDocs]
* [PowerShell Documentation][PowerShellDocs]

---
_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._
_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
[GitHubRepo]: https://github.com/Azure/azure-powershell/issues

[Contributing]: CONTRIBUTING.md

[AzureIcon]: documentation/images/MicrosoftAzure-32px.png
[PowershellIcon]: documentation/images/MicrosoftPowerShellCore-32px.png
[AzurePowerShelModules]: documentation/azure-powershell-modules.md
[AzurePowerShellModules]: documentation/azure-powershell-modules.md
[DeveloperGuide]: documentation/development-docs/azure-powershell-developer-guide.md

<!-- External -->
Expand All @@ -186,16 +214,21 @@ _This project has adopted the [Microsoft Open Source Code of Conduct][CodeOfCond
[CodeOfConductFaq]: https://opensource.microsoft.com/codeofconduct/faq/
[OpenCodeEmail]: mailto:[email protected]

[AzureCloudShell]: https://shell.azure.com/
[AzureCommunitySupport]: https://azure.microsoft.com/support/community/
[PrivacyStatement]: https://privacy.microsoft.com/privacystatement

<!-- 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-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/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
[MicrosoftAzureDocs]: https://learn.microsoft.com/azure/
[PowerShellDocs]: https://learn.microsoft.com/powershell/

[InstallationGuide]: https://learn.microsoft.com/powershell/azure/install-az-ps
[GettingStartedGuide]: https://learn.microsoft.com/powershell/azure/get-started-azureps
[PersistedCredentialsGuide]: https://learn.microsoft.com/powershell/azure/context-persistence

[ConnectAzAccount]: https://learn.microsoft.com/powershell/module/az.accounts/connect-azaccount
[GetAzContext]: https://learn.microsoft.com/powershell/module/az.accounts/get-azcontext
[GetAzSubscription]: https://learn.microsoft.com/powershell/module/az.accounts/get-azsubscription
[SetAzContext]: https://learn.microsoft.com/powershell/module/az.accounts/set-azcontext
[SendFeedback]: https://learn.microsoft.com/powershell/module/az.accounts/send-feedback
[DisableAzDataCollection]: https://learn.microsoft.com/powershell/module/az.accounts/disable-azdatacollection

0 comments on commit 3c1572d

Please sign in to comment.