Generation Process

Generation Process

Introduction

Before the SDK is generated, we first capture both v1.0 and beta metadata from the Microsoft Graph service. This is captured every week and stored in microsoftgraph/msgraph-metadata repo where it is cleaned and injected with descriptions from Microsoft Graph docs.

The clean metadata is then converted to an OpenAPI document using DevX API. This produces an OpenAPI V3 document in yaml that describes all API paths in Microsoft Graph.

Given the large surface area of Microsoft Graph, we slice the resultant OpenAPI document into smaller module specific documents using the mapping found in ModulesMapping.jsonc.

Each module specific OpenAPI document is then ran through AutoREST.PowerShell to generate a PowerShell binary module containing models and cmdlets.

We then wire-up the generated module with our Microsoft Graph Core .NET SDK and MSAL.NET to setup an HTTP pipeline that is pre-configured with a number of middleware such as authentication handler, retry handler, redirect handler, compression handler, etc.

The generated cmdlets can further be modified using customization directives. Scenario based cmdlets can also be added using code level customization. See customization section below for more details.

Once all the modules are generated, we pack them into .nupkg files and publish to PowerShell Gallery.

N.B - Generating the SDK is currently limited to only Windows, but we have plans to support Linux and MacOS in the future. The SDK can however be used on any platform (Windows, Linux, or MacOS).

SDK Generation

Prerequisite

Service

• Service design is finalized, and schema is published to either v1.0 or beta metadata.

Tools

• Download and install PowerShell 6 or greater.

• Install AutoREST using npm. This requires NodeJS to be installed on your system.

  npm install -g "autorest"

• Install .NET Core SDK 2.2 or greater.

  npm install -g dotnet-sdk-2.2

• Clone msgraph-sdk-powershell repo locally.

  git clone https://github.com/microsoftgraph/msgraph-sdk-powershell.git

Generation Steps

1. Generate Microsoft.Graph.Authentication module

   # Set Environment variables required by tests
   $env:TENANTIDENTIFIER="<Your MsGraph Tenant Identifier(GUID)>"
   $env:CLIENTIDENTIFIER="<Identifier(GUID) to a registered Client Application in your Tenant>"
   $env:DEFAULTUSERID="<Identifier(GUID) to a user in your MsGraph Tenant>"
   
   # Read a pfx file file from storage that has been added to the registered Client Application
   $pfxFileName = "<path to *.pfx file>"
   $pfxFileContent = Get-Content $pfxFileName -AsByteStream -Raw
   $pfxFileContentEncoded = [convert]::ToBase64String($pfxFileContent)
   
   #A base64 string of a *.pfx certificate that has been added to registered Application above
   $env:CLIENTCERTIFICATE = $pfxFileContentEncoded
   
   # Builds and runs all enabled tests.
   \msgraph-sdk-powershell\tools\GenerateAuthenticationModule.ps1 -Build -Test

2. Generate service modules

   Ensure modules mapping is up to date and your services’ entity set or singleton are properly mapped to a module.

   # Holds a mapping of APIs to module.
   \msgraph-sdk-powershell\config\ModulesMapping.jsonc

   • Update both v1.0 and beta OpenAPI documents (optional).

     # Refreshes all OpenAPI documents with the latest metadata.
     \msgraph-sdk-powershell\tools\UpdateOpenApi.ps1 # (v1.0)
     \msgraph-sdk-powershell\tools\UpdateOpenApi.ps1 -BetaGraphVersion # (beta)

   • Generate beta and v1.0 profiles (optional).

     # Generates a version profile of all modules.
     \msgraph-sdk-powershell\tools\GenerateProfiles.ps1

   • Generate service modules.

     • To generate all service modules present in the SDK, run:

       # Builds amd runs all enabled tests
       \msgraph-sdk-powershell\tools\GenerateModules.ps1 -Build -Test

       This generates, builds, and runs all enabled tests for all the modules defined in modules mapping config file and can take several hours.

     • Optionally, you can generate the modules that you are interested in by specifying an array of module names to -ModulesToGenerate parameter when running GenerateModule.ps1:

       \msgraph-sdk-powershell\tools\GenerateModules.ps1 -Build -Test –ModulesToGenerate "Users", "DeviceManagement.Administration"

3. Generate Microsoft.Graph module (meta/roll-up module)

   # Generates roll-up module.
   \msgraph-sdk-powershell\tools\GenerateRollUpModule.ps1

Customization

This involves making modification to the generated commands in the service modules. Before making any customization to the generated cmdlets, please read through the PowerShell Design Guidelines.

Customization can generally be done in two ways:

• Through directives:
  • See https://github.com/Azure/autorest.powershell/blob/master/docs/directives.md
• Through code level customization:
  • See https://github.com/Azure/autorest.powershell/blob/master/docs/customization.md

References

• AutoREST.PowerShell Guide - https://github.com/Azure/autorest.powershell/tree/master/docs.
• Contribution guide - https://github.com/microsoftgraph/msgraph-sdk-powershell/blob/dev/CONTRIBUTING.md.
• Examples:
  • Complete generated module with directives - https://github.com/microsoftgraph/msgraph-sdk-powershell/tree/dev/src/Applications/Applications.
  • Scenario based cmdlets through code level customization - https://github.com/microsoftgraph/msgraph-sdk-powershell/tree/dev/src/Groups/Groups/custom.