Skip to content

Microsoft Azure PowerShell Developer Guide

Jump to bottom Edit New page
matt-gibbs edited this page Oct 29, 2014 · 32 revisions

##Get it! A normal git geek can clone the repo.

Configuring Visual Studio

Development Environment

  • You need to have this environment variable setup EnableNuGetPackageRestore=true
  • Use Visual Studio 2013 (never use 2012 as the build may fail)

Prerequisites

Change PowerShell execution policy

Change machine's PowerShell execution policy to Unrestricted (see this to know how to change it). Make sure that this change is applied to PowerShell.exe under System32 and SysWOW64:

  • C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
  • C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe

Install Prerequisites

Option #1, Automatically install prerequisites by executing tools\Build.ps1

Option #2, or do it manually by installing these:

  • Install Windows Azure SDK
  • Install Python 2.7 x86
  • Install Django
  • Install Wix 3.8
  • Make sure that git.exe and wix bin folder are in you PATH environment variable.
  • Set environment variable EnableNuGetPackageRestore to value true

Build the solution

  • Execute tools\Build.ps1

Running unit tests

  • Execute tools\RunCheckInTests.ps1

Enable running Windows PowerShell when debugging

  • Choose any project and set it as startup project.
  • Open this project properties.
  • Go to Debug tab.
  • Under Start Action pick Start external program and type Windows PowerShell directory (i.e. C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe)

Importing modules automatically when start debugging

  • Assuming the Debug page is opened, go to Start Options
  • In Command line arguments type this command
-NoExit -Command "Import-Module <Modules to import>"
  • For example this command loads module manifest:
-NoExit -Command "Import-Module <Path to Azure.psd1>\Azure.psd1"

It's recommended to enable verbose as it's enabled by default when using Windows Azure PowerShell shortcut

-NoExit -Command "Import-Module <Path to Azure.psd1>\Azure.psd1;$VerbosePreference='Continue'"

Adding new scenario test

Configuring scenario test code

  • Create a new class in either Commands.ScenarioTests or Commands.XXXX.Test (where XXX is the name of the resource provider)
    • If setting up a new project add reference to Commands.ScenarioTests.Common
    • If setting up a new project set post build event to xcopy "$(SolutionDir)Package\$(ConfigurationName)\*.*" $(TargetDir) /Y /E
    • Add reference to any project that will be tested
  • Create a ps1 file in the same folder that contains 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 exception is being thrown
    • Use Assert-ThrowsContains scriptblock substring to verify 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 the object is null
    • Use Assert-NotNull object to verify that the object is not null
    • Use Assert-Exists path to verify that the file exists
    • Use Assert-AreEqualArray a1 a2 to compare arrays
  • Add a private variable EnvironmentSetupHelper helper to the test class
  • Set each test as an XUnit test that does the following: 
              // Enable undo functionality as well as mock recording
          using (UndoContext context = UndoContext.Current)
          {
              // Configure recordings
              context.Start(TestUtilities.GetCallingClass(), TestUtilities.GetCurrentMethodName());

              // See explanation below
              SetupManagementClients();

              // Specify either ResourceManager or ServiceManagement mode
              helper.SetupEnvironment(AzureModule.AzureResourceManager);

              // Add all ps1 files used in the test
              helper.SetupModules(AzureModule.AzureResourceManager, "ScenarioTests\\Common.ps1",
                  "ScenarioTests\\" + this.GetType().Name + ".ps1");

              // Run actual test
              helper.RunPowerShellTest(scripts);
          }
  • Add SetupManagementClients() method that creates instances of clients used in the actual test and adds them to the helper 
      // Create clients via TestBase.GetServiceClient to setup mocking
  var client1 = TestBase.GetServiceClient<ResourceManagementClient>(new CSMTestEnvironmentFactory());
  var client2 = TestBase.GetServiceClient<XXXX>(new RDFETestEnvironmentFactory());

  helper.SetupManagementClients(client1, client2);
  // Alternatively call helper.SetupSomeOfManagementClients(...) if not all clients can be pre-initialized
  // Any client not passed in to this method will not be recorded

See https://github.com/Azure/azure-sdk-tools/blob/dev/src/ResourceManager/Resources/Commands.Resources.Test/ScenarioTests/ResourcesTestsBase.cs for an example of the above setup.

Setup for scenario tests

Using AD (works for CSM and RDFE)
  • Set TEST_CSM_ORGID_AUTHENTICATION environment variable for CSM testing
  • Set TEST_ORGID_AUTHENTICATION environment variable for RDFE testing
  • Execute tools\SetupHttpRecordEnv.ps1 to know how the environment variable contents are expected to be.
Using Certificate (works for RDFE only)
  • In a Windows Azure storage, create a new container called testcredentials-production
  • upload these three files there:
    • default.publishsettings: that's publish settings file used in the tests
    • environment.yml: these are environment variables you want to inject (check yml file format)
    • variables.yml: these are PowerShell variables you want to inject
  • On your machine set these environment variables:
    • AZURE_TEST_ENVIRONMENT=production
    • AZURE_STORAGE_ACCOUNT=<storage account name>
    • AZURE_STORAGE_ACCESS_KEY=<storage account key>
  • Run scenario tests by executing this cmd: msbuild build.proj /t:Scenariotest

AD Scenario Tests

Create these environment variables for the AD scenario tests:

  • AZURE_LIVEID should be a 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_PRINCPAL 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

  • Finish what is in section Running scenario tests
  • Execute tools\SetupHttpRecordEnv.ps1
  • Run the test and make sure that you got a generated *.json file that matches the test name in the bin folder under SessionRecords folder
  • Copy SessionRecords folder inside the test project and add all *.json files in Visual Studio setting "Copy to Output Directory" property to "Copy if newer"
  • To assure that the records work fine, change AZURE_TEST_MODE to Playback and run the test which should be run mocked not live.

Preliminary Steps for adding new project (RDFE or CSM):

Adding new Service Management (RDFE) project

When adding a new Service Management project please follow these guidelines:

  • Add new folder under ServiceManagement that have your service specific name. Use the same name that would be visible on the portal and do not use generic names.
  • Under the newly created folder create the corresponding cmdlets and test project following the same naming convention in ManagedCache folder projects.
  • The new code should depend on the Commands.Common* projects only and if there are other external dependencies coming from a project in old code please contact us back to sort this out.
  • The project should not have a direct dependency on the storage SDK and should rely on Commands.Common.Storage
  • The cmdlets code must follow the convenience client convention (check Test-AzureResourceGroupTemplate cmdlet src code) meaning that the cmdlet src code file should minimum required business logic and just call the convenience client.
  • The scenario tests should be added in Commands.ScenarioTest and follow same convention that Resources have.
  • Upon submitting the PR make sure to record mocks for thee scenario tests and check-in them as well.
  • No need to have C# unit tests unless there is a need for deep testing ti a specific method in a class.

Adding new Resource Manager (CSM) project

When adding a new Resource Manager project please follow these guidelines:

  • Add new folder under ResourceManager that have your service specific name. Use the same name that would be visible on the portal and do not use generic names.
  • Under the newly created folder create the corresponding cmdlets and test project following the same naming convention in Resource folder projects.
  • The new code should depend on the Commands.Common* projects only and if there are other external dependencies coming from a project in old code please contact us back to sort this out.
  • The project should not have a direct dependency on the storage SDK and should rely on Commands.Common.Storage
  • The cmdlets code must follow the convenience client convention (check Test-AzureResourceGroupTemplate cmdlet src code) meaning that the cmdlet src code file should minimum required business logic and just call the convenience client.
  • The scenario tests should be added in Commands.ScenarioTest and follow same convention that Resources have.
  • Upon submitting the PR make sure to record mocks for thee scenario tests and check-in them as well.
  • No need to have C# unit tests unless there is a need for deep testing ti a specific method in a class.

Misc

Understanding piping

In Powershell cmdlets pipe objects between one another. Cmdlets should not return text, they should return objects.

For example, if you use our Azure cmdlets, you can do the following

Get-AzureWebsite | Remove-AzureWebsite

Get-AzureWebsite will return a set of Website objects and then invoke Remove-AzureWebsite passing each object one by one.

Piping in

As long as the property names of the objects getting returned from Get-AzureWebsite match those of Remove-AzureWebsite, and Remove-AzureWebsite's properties are properly annotated with [Parameter(ValueFromPipeline)], then piping between them works.

In this case, the RemoveAzureWebsite and GetAzureWebsite classes both inherit from WebsitesBaseCmdlet. This base class includes a "Name" parameter which is properly annotated as is shown below:

[Parameter(Position = 0, Mandatory = false, ValueFromPipelineByPropertyName = true, HelpMessage = "The web site name.")]
[ValidateNotNullOrEmpty]
public string Name
{
   get;
   set;
}

ValueFromPipelineByPropertyName=true instructs Powershell to try to match any objects coming in from the pipeline by the property name and type. If it finds a match then the value will be plugged in. Multiple properties can be annotated in this way.

Piping out

To pipe out, you use the cmdlet's WriteObject method. This will then write the objects out to the pipeline. Below is an example of how this is done in the GetAzureWebsite class.

protected virtual void WriteWebsites(IEnumerable<Site> websites)
{
    WriteObject(websites, true);
}

For more information on piping, see the following links:

Getting a MAML generated lib used in Azure PowerShell

  • Create/Update specs project in the specs repo and send pull request
  • Wait until it gets merged and then publish it using this job. Note that you need to provide your package name
  • Update the corresponding MAML lib and send pull request to .NET SDK repo
  • Wait until it gets merged and then publish the MAML package using this job. Make sure that when you publish it's safe for other MAML libs
  • Now you can use the published lib in Azure PowerShell by consuming it as NuGet package
Add a custom footer

RS Vault Backup
Coding Guidelines

Clone this wiki locally