Skip to content

Microsoft Azure PowerShell Developer Guide

Jump to bottom Edit New page
Abdelrahman Elogeel edited this page Jul 9, 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:

Build the solution

  • Execute tools\Build.ps1

Running unit tests

  • Execute tools\RunCheckInTests.ps1

Running scenario tests

  • 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

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

  • Finish what is in section Running scenario tests
  • Add new environment variable called AZURE_TEST_MODE and set it to Record
  • Run the test and make sure that you got a generated *.json file that matches the test name
  • 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