Microsoft Graph PowerShell SDK (alpha)

The Microsoft Graph PowerShell SDK is a collection of PowerShell modules that contain cmdlets for calling Microsoft Graph.

Installing the Microsoft.Graph.Beta Module

In the future, the modules will be published to the PowerShell Gallery, however in the short term they are hosted on our own nuget feed. Use the following commands to register repository and then install the Microsoft.Graph.Beta module from there.

Register-PSRepository `
-Name GraphPowerShell `
-SourceLocation https://graphpowershellrepository.azurewebsites.net/nuget

# Installing the Graph PowerShell module for the Beta API 
Install-module Microsoft.Graph.Beta -Repository GraphPowerShell

There are a set of samples in the samples folder to help getting started with the library.

Generate Module

Prerequisite

Download and install PowerShell Core.
Install AutoRest.
```
npm install -g "@autorest/autorest"
```
Create an Azure DevOps Artifacts Feed or host a local Nuget.Server, and register it as a local PowerShell repository using Register-PSRepository command. Once done, take note of the RepositoryName and APIKey. You can always get the repository name by running Get-PSRepository. This will be used as a temporary repository to publish generated modules in order to specify them as dependencies for Microsoft.Graph roll-up module.

N.B - Once we have a preview version of the modules in PowerShell Gallery, this step won't be needed.

Generation Steps

Clone the msgraph-sdk-powershell repo locally.

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

Generate, pack and optionally publish Microsoft.Graph.Authentication module.

. \msgraph-sdk-powershell\tools\GenerateAuthenticationModule.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish

Generate, pack and optionally publish Microsoft Graph service PowerShell modules by tags. For a complete list of tags, see OpenApiSplice.

Edit .\config\ModulesMapping.jsonc by adding key-value pairs of the tags you want to generate modules for. The key is the name of the module to be generated and the value is a regex expression that will be used to query OpenApiSplice for an OpenAPI document for your module.

To generate v1.0 modules, run the following script:
```
. \msgraph-sdk-powershell\tools\GenerateModules.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
```
To generate beta endpoint modules, add -BetaGraphVersion switch when running GenerateModules.ps1.

This performs the following actions :
- Generates the modules specified in .\config\ModulesMapping.jsonc in .\msgraph-sdk-powershell\src\{GraphVersion}\{Module-Name}\{Module-Name}\.
- Adds appropriate dependencies to the generated modules.
- Packs and optionally publishes the modules to the specified repository as .nupkg files. The generated nupkg can be found in .\msgraph-sdk-powershell\artifacts\{GraphVersion}\{Module-Name}\.
Generate, pack and optionally publish Microsoft.Graph roll-up module.
```
. \msgraph-sdk-powershell\tools\GenerateRollUpModule.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
```
To generate a roll-up module for Microsoft Graph beta modules, add -BetaGraphVersion switch when running GenerateRollUpModule.ps1.

The above script generates a Microsoft.Graph module manifest with the generated Microsoft Graph service modules specified in .\config\ModulesMapping.jsonc and Microsoft.Graph.Authentication module as its dependencies.

Optionally, manually publish modules from an artifacts location.

. \msgraph-sdk-powershell\tools\PublishModule.ps1 -Modules "Graph", "Authentication", "Subscriptions", "Teams" -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ArtifactsLocation {ArtifactsLocation}

Common Generation Scripts Parameters

-ModuleVersion: The version of the module to generate. This defaults to 0.1.0 when not specified.
-ModulePreviewNumber: An optional preview number of the module(s) to generate. When not specified, the module is generated as a non preview module(s) of the ModuleVersion.
-Publish: An optional switch that publishes generated module(s) to the specified RepositoryName. This used when module dependencies are not locally installed in your machine.
-BetaGraphVersion: A switch that indicates tells the generation scripts to generate beta modules of Microsoft Graph. If not specified, the generation scripts will generate v1.0 modules.

Run Generated Modules

By default, the generated modules should already be installed on your PC in %UserProfile%\Documents\PowerShell\Modules as part of the generation process. If it's not present or you want to install the modules on another machine, then install them as such by specifying your repository name:
```
Install-Module Microsoft.Graph -Repository {RepositoryName} # v1.0 modules
or
Install-Module Microsoft.Graph.Beta -Repository {RepositoryName} # beta modules
```

Authenticate to Microsoft Identity to get an access token to call Microsoft Graph modules.

Delegated access via Device Code Flow.
```
Connect-Graph -Scopes "User.Read.All"
```

App only access via Client Credential Flow with a certificate.

# Replace CN=DaemonConsoleCert with your certificate name.
Connect-Graph -ClientId ClientId -TenantId TenantId -CertificateName "CN=DaemonConsoleCert"

Call Get-User command.

# Authenticate for delegated access.
Connect-Graph

Get-User -Top 10 -Select Id, DisplayName, BusinessPhones | Format-Table Id, DisplayName, BusinessPhones

Call Get-UserMessage cmdlet.

# Authenticate for app only access.
Connect-Graph -ClientId ClientId -TenantId TenantId -CertificateName CertificateName

Get-UserMessage -UserId UserId -Top 10 -Skip 10 -Select Id, Subject, CreatedDateTime | Format-Table CreatedDateTime, Subject, Id

Sign out of the current logged in context i.e. app only or delegated access.
```
Disconnect-Graph
```