Skip to content

Latest commit

 

History

History
362 lines (250 loc) · 22.6 KB

azure-powershell-developer-guide.md

File metadata and controls

362 lines (250 loc) · 22.6 KB
Raw

Azure PowerShell Developer Guide

The Azure PowerShell Developer Guide was created to help with the development and testing of Azure PowerShell cmdlets. This guide contains information on how to set up your environment, create a new project, implement cmdlets, record and run tests, and more.

Table of Contents

Prerequisites

The following prerequisites should be completed before contributing to the Azure PowerShell repository:

Environment Setup

GitHub Basics

If you don't have experience with Git and GitHub, some of the terminology and process can be confusing. Here is a guide to understanding the GitHub flow and here is a guide to understanding the basic Git commands.

To develop in the Azure PowerShell repository locally, you first need to create your own fork. For more information on how to fork, click here.

Once your fork of the Azure PowerShell repository has been created, you need to clone your fork to your local machine. To do so, run the following command:

git clone https://github.com/<YOUR GITHUB USERNAME>/azure-powershell.git

You now be able to create your own branches, commit changes, and push commits to your fork.

Note: we recommend adding the Azure/azure-powershell repository to your list of tracked repositories in Git. This allows you to easily pull changes from the Azure repository. To do this, run the following command:

git remote add upstream https://github.com/Azure/azure-powershell.git

Then, to pull changes from the master branch in Azure/azure-powershell into your local working branch, run the following command:

git pull upstream master

Building the Environment

Note: to build the environment locally, you need platyPS install on your machine. Please see the Prerequisites section for details on how to install this module.

After cloning the repository to your local machine, you want to ensure that you can build the environment. To do so, launch VS Developer Command Prompt (which is installed with Visual Studio) and run the following command (from the root of the repository) to do a full build:

msbuild build.proj

Alternatively, you can open any command prompt (Command Prompt, Windows PowerShell, or PowerShell Core), navigate to the root of the repository, and run:

PS C:\azure-powershell> dotnet msbuild build.proj

Skipping Help Generation During Build

By default, we build the dll-Help.xml files (used to display the help content for cmdlets in PowerShell) from markdown using the platyPS module. Since this help generation step can take 10-15 minutes, we have added the ability to skip it as a part of the command line build process:

msbuild build.proj /p:SkipHelp=true

Running Tests

Launch VS Developer Command Prompt and run the following command (from the root of the repository) to run all of the tests:

msbuild build.proj /t:Test

Alternatively, you can open any command prompt (Command Prompt, Windows PowerShell, or PowerShell Core), navigate to the root of the repository, and run:

PS C:\azure-powershell> dotnet msbuild build.proj /t:Test

Before Adding a New Project

.NET SDK

Before adding a new project to Azure PowerShell, you must have generated an SDK for .NET using AutoRest for your service, and it must have been merged into the repository.

For more information about on-boarding a new library in the SDK for .NET repository, click here.

Design Review

Before development, you must meet with the Azure PowerShell team to have a design review for your proposed PowerShell cmdlets. We advise that this review is held no earlier than three weeks out from code complete of the release you want to ship the cmdlets with. For a small number of cmdlet changes and/or additions, an email containing the markdown files for the proposed changes is suggested. For a large number of changes and/or additions, a meeting is required with the Azure PowerShell team.

Before submitting a design review, please be sure that you have read the Azure PowerShell Design Guidelines document.

Please submit a design review here: https://github.com/Azure/azure-powershell-cmdlet-review-pr

Note: You will need to be part of the GitHub Azure org to see this repository. Please go to this link to become part of the Azure org.

We recommend using the platyPS module to easily generate markdown files that contains the above information and including the files in the design submission.

Point of Contact

You must provide a contact (Microsoft alias + GitHub alias) on your team that is responsible for handling issues with your SDK and cmdlets, as well as open source contributions to your code.

Also, members of your team (who are involved with the SDKs) are advised to join the Microsoft Teams Azure SDK team, and join the adxsdkpartners alias on idweb.

Setting Up a New Project

Getting Started

When adding a new ResourceManager project, please follow these guidelines:

Creating the Project

Add a new folder under src/ResourceManager with your service specific name (e.g., Compute, Sql, Websites).

We recommend copying an existing module. For example, go to src/ResourceManager/Media and copy the contents of this folder. Paste these to your service folder you just created. Rename the following:

  • The folders to Commands.<SERVICE> and Commands.<SERVICE>.Test
  • The solution to <SERVICE>.sln
  • The projects (within each folder) to Commands.<SERVICE>.csproj and Commands.<SERVICE>.Test.csproj
  • The PSD1 file (in the Commands.<SERVICE> folder) to Az.<SERVICE>.psd1

Now, you'll need to edit the solution file. Open the <SERVICE>.sln in your text editor of choice. Edit these lines to use your <SERVICE> name:

  • Update the "Commands.<SERVICE>.Netcore", "Commands.<SERVICE>\Commands.<SERVICE>.Netcore.csproj"
  • Update the "Commands.<SERVICE>.Test.Netcore", "Commands.<SERVICE>.Test\Commands.Media.Test.Netcore.csproj"

After the solution file is updated, save and close it. Now, open the solution file in Visual Studio. Right click on the Commands.<SERVICE> project in the Solution Explorer and select Unload project. Right click on the unloaded project and select Edit Commands.<SERVICE>.csproj. Once opened, ensure that the following things are changed:

  • The AssemblyNamespace and RootNamespace attributes of the project must be changed to Microsoft.Azure.PowerShell.Cmdlets.<SERVICE>. If these changes are not made, then the assembly produced from this project is not be signed and results in errors when users try to use your module.
  • Change the OutputPath attribute to $(ProjectDir)..\..\..\Package\$(Configuration)\ResourceManager\AzureResourceManager\Az.<SERVICE>\
  • Change the particular <ItemGroup> containing <None Include="Az.<SERVICE>.psd1">

Right click on the project and select Reload project, and then build the solution by either right clicking on the solution and selecting Rebuild Solution or, from the top of Visual Studio, selecting Build > Rebuild Solution. If the build does not succeed, open the .csproj file and ensure there are no errors.

Adding Project References

There are a few existing projects that need to be added before developing any cmdlets. To add a project to the solution, right click on the solution in Solution Explorer and select Add > Existing Project. This allows you to navigate through folders to find the .csproj of the project you want to add. Once a project is added to your solution, you can add it as a reference to the Commands.<SERVICE> project by right clicking on Commands.<SERVICE> and selecting Add > Reference. This opens the Reference Manager window, and once you have selected the Projects > Solution option on the left side of the window, you are able to select which projects you want to reference in Commands.<SERVICE> by checking the box to the left of the name.

Creating Cmdlets

PowerShell Cmdlet Design Guidelines

Please check out the PowerShell Cmdlet Design Guidelines page for more information on how to create cmdlets that follow the PowerShell guidelines.

Enable Running PowerShell when Debugging

  • Choose any project and set it as the startup project in Visual Studio
    • Right click on your project in the Solution Explorer and select Set as StartUp project
  • Right-click on the project and select Properties
  • Go to the Debug tab
  • Under Start Action, pick Start external program and type the PowerShell directory
    • For example, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe

Importing Modules

To import modules automatically when debug has started, follow the below steps:

  • In the Debug tab mentioned previously, go to Start Options
  • Import the Profile module, along with the module you are testing, by pasting the following in the Command line arguments box (note: you have to update the <PATH_TO_REPO> and values provided below):
    • -NoExit -Command "Import-Module <PATH_TO_REPO>/src/Package/Debug/ResourceManager/AzureResourceManager/Az.Accounts/Az.Accounts.psd1;Import-Module <PATH_TO_REPO>/src/Package/Debug/ResourceManager/AzureResourceManager/Az.<SERVICE>/Az.<SERVICE>.psd1;$VerbosePreference='Continue'"
  • Note: if you do not see all of the changes you made to the cmdlets when importing your module in a PowerShell session (e.g., a cmdlet you added is not recognized as a cmdlet), you may need to delete any existing Azure PowerShell modules that you have on your machine (installed through the PowerShell Gallery) before you import your module.

Adding Help Content

All cmdlets that are created must have accompanying help that is displayed when users execute the command Get-Help <your cmdlet>.

Each cmdlet has a markdown file that contains the help content that is displayed in PowerShell; these markdown files are created (and maintained) using the platyPS module.

For complete documentation, see help-generation.md in the documentation folder.

Adding Tests

Note: As mentioned in the prerequisites section, set the PowerShell execution policy to Unrestricted for the following versions of PowerShell:

  • C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
  • C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe
  • C:\Program Files\PowerShell\{{version}}\pwsh.exe

Using Azure TestFramework

Please see our guide on Using Azure TestFramework for information on how to setup the appropriate connection string and record tests using the Microsoft.Rest.ClientRuntime.Azure.TestFramework package.

Scenario Tests

Adding Scenario Tests

  • Create a new class in Commands.<SERVICE>.Test
  • Create a ps1 file in the same folder that contains the actual tests (see sample)
    • Use Assert-AreEqual x y to verify that values are the same
    • Use Assert-AreNotEqual x y to verify that values are not the same
    • Use Assert-Throws scriptblock message to verify an exception is being thrown
    • Use Assert-ThrowsContains scriptblock substring to verify an exception is being thrown and contains a substring
    • Use Assert-Env env[] to verify environment variables
    • Use Assert-True scriptblock to verify that a script block returns true
    • Use Assert-False scriptblock to verify that a script block returns false
    • Use Assert-Null object to verify that an object is null
    • Use Assert-NotNull object to verify that an object is not null
    • Use Assert-Exists path to verify that a file exists
    • Use Assert-AreEqualArray a1 a2 to verify that arrays are the sam

Using Active Directory

  • Use the Set-TestEnvironment cmdlet from Repo-Tasks.psd1 to setup your connection string
  • Alternatively, you can set the following environment variables
    • TEST_CSM_ORGID_AUTHENTICATION is used for Resource Manager testing

Important!

  1. Be sure that you have set the ExecutionPolicy to Unrestricted on both 32-bit and 64-bit PowerShell environments, as mentioned in the prerequisites at the top
  2. When recording tests, if you are using a Prod environment, use ServicePrincipalName (SPN) and ServicePrincipalSecret. For more information on creating an SPN, click here.

AD Scenario Tests

Create these environment variables for the AD scenario tests:

  • AZURE_LIVEID should be UserId and Password for a valid LiveId account.
    • AZURE_LIVEID=UserId=<user@hotmail.com>;Password=<Password>
  • AZURE_ORGID_FPO should be an orgid and password for an account that does not have any subscriptions or role assignments associated with it. It is supposed to be a foreign principal in your current tenant.
    • AZURE_ORGID_FPO=UserId=<user@orgid.com>;Password=<Password>
  • AZURE_ORGID_ONE_TENANT_ONE_SUBSCRIPTION should be an account that is in a single tenant and has access to the subscription managed by that AD tenant.
  • AZURE_ORGID_ONE_TENANT_ONE_SUBSCRIPTION=UserId=<user@orgid.com>;Password=<Password>;SubscriptionId=<SubscriptionId>;AADAuthEndpoint=https://login.windows.net/
  • AZURE_SERVICE_PRINCIPAL should be a service principal - an application defined in the subscription's tenant - that has management access to the subscription (or at least to a resource group in the tenant)
    • AZURE_SERVICE_PRINCIPAL=UserId=<UserGuid>;Password=<Password>;AADTenant=<TenantGuid>;SubscriptionId=<SubscriptionId>

Recording/Running Tests

  • Set up environment variables using New-TestCredential as described here
  • Run the test in Visual Studio in the Test Explorer window and make sure you got a generated JSON file that matches the test name in the bin folder under the SessionRecords folder
  • Copy this SessionRecords folder and place it inside the test project
    • Inside Visual Studio, add all of the generated JSON files, making sure to change the "Copy to Output Directory" property for each one to "Copy if newer"
    • Make sure that all of these JSON files appear in your Commands.<SERVICE>.Test.csproj file

After Development

Once all of your cmdlets have been created and the appropriate tests have been added, you can open a pull request in the Azure PowerShell repository to have your cmdlets added to the next release. Please make sure to read CONTRIBUTING.md for more information on how to open a pull request, clean up commits, make sure appropriate files have been added/changed, and more.

Change Log

Whenver you make updates to a project, please make sure to update the corresponding service's ChangeLog.md file with a snippet of what you changed under the Upcoming Release header. This information is later used for the release notes that goes out with each module the next time they are released, and provides users with more information as to what has changed in the module from the previous release. For more information on updating change logs can be found in CONTRIBUTING.md

Misc

Publish to PowerShell Gallery

To publish your module to the official PowerShell gallery or the test gallery site, contact the Azure PowerShell team

AsJob Parameter

All long running operations must implement the -AsJob parameter, which will allow the user to create jobs in the background. For more information about PowerShell jobs and the -AsJob parameter, read this doc.

To implement the -AsJob parameter, simply add the parameter to the end of the parameter list:

[Parameter(Mandatory = false, HelpMessage = "Run cmdlet in the background")]
public SwitchParameter AsJob { get; set; }

Once you add the parameter, please manually test that the job is created and successfully completes when the parameter is specified. Additionally, please ensure that the help files are updated with this parameter.

To ensure that -AsJob is not broken in future changes, please add a test for this parameter. To update tests to include this parameter, use the following pattern:

$job = Get-AzSubscription
$job | Wait-Job
$subcriptions = $job | Receive-Job

Argument Completers

PowerShell uses Argument Completers to provide tab completion for users. At the moment, Azure PowerShell has two specific argument completers that should be applied to relevant parameters, and one generic argument completer that can be used to tab complete with a given list of values. To test the completers, run a complete build after you have added the completers (msbuild build.proj) and ensure that the psm1 file (Az.<Service>.psm1) has been added to the psd1 file found in src/Package/Debug/ResourceManager/AzureResourceManager/AzureRM.<Service>/AzureRM.<Service>.psd1 under "Root Module".

Resource Group Completer

For any parameter that takes a resource group name, the ResourceGroupCompleter should be applied as an attribute. This will allow the user to tab through all resource groups in the current subscription.

using Microsoft.Azure.Commands.ResourceManager.Common.ArgumentCompleters;
...
[Parameter(Mandatory = false, HelpMessage = "The resource group name")]
[ResourceGroupCompleter]
public string ResourceGroupName { get; set; }

Resource Name Completer

For any parameter that takes a resource name, the ResourceNameCompleter should be applied as an attribute. This will allow the user to tab through all resource names for the ResourceType in the current subscription. This completer will filter based upon the current parent resources provided (for instance, if ResourceGroupName is provided, only the resources in that particular resource group will be returned). For this completer, please provide the ResourceType as the first argument, followed by the parameter name for all parent resources starting at the top level.

using Microsoft.Azure.Commands.ResourceManager.Common.ArgumentCompleters;
...
[Parameter(Mandatory = false, HelpMessage = "The parent server name")]
[ResourceNameCompleter("Microsoft.Sql/servers", nameof(ResourceGroupName))]
public string ServerName { get; set; }

[Parameter(Mandatory = false, HelpMessage = "The database name")]
[ResourceNameCompleter("Microsoft.Sql/servers/databases", nameof(ResourceGroupName), nameof(ServerName))]
public string Name { get; set; }

Location Completer

For any parameter that takes a location, the LocationCompleter should be applied as an attribute. In order to use the LocationCompleter, you must input as an argument all of the Providers/ResourceTypes used by the cmdlet. The user will then be able to tab through locations that are valid for all of the Providers/ResourceTypes specified.

using Microsoft.Azure.Commands.ResourceManager.Common.ArgumentCompleters;
...
[Parameter(Mandatory = false, HelpMessage = "The location of the resource")]
[LocationCompleter("Microsoft.Batch/operations")]
public string Location { get; set; }

Generic Argument Completer

For any parameter which you would like the user to tab through a list of suggested values (but you do not want to limit the users to only these values), the generic argument completer should be added.

using Microsoft.Azure.Commands.ResourceManager.Common.ArgumentCompleters;
...
[Parameter(Mandatory = false, HelpMessage = "The tiers of the plan")]
[PSArgumentCompleter("Basic", "Premium", "Elite")]
public string Tier { get; set; }