How to generate customized Microsoft Graph client with Kiota

Microsoft Graph SDKs

The Microsoft Graph SDKs simplifies applications that access Microsoft Graph. The SDKs consist of two components:

  • a service library - models and request builders generated from Microsoft Graph metadata
  • a core library - enhance working with all the Microsoft Graph services, support for retry handling, secure redirects, transparent authentication, and payload compression

Supported languages

The Graph SDKs are currently available for the following languages

Language v1.0 beta
C# https://github.com/microsoftgraph/msgraph-sdk-dotnet https://github.com/microsoftgraph/msgraph-beta-sdk-dotnet
CLI https://github.com/microsoftgraph/msgraph-cli https://github.com/microsoftgraph/msgraph-beta-cli
PowerShell https://github.com/microsoftgraph/msgraph-sdk-powershell -
TypeScript/JavaScript https://github.com/microsoftgraph/msgraph-sdk-javascript https://github.com/microsoftgraph/msgraph-beta-sdk-typescript
Java https://github.com/microsoftgraph/msgraph-sdk-java https://github.com/microsoftgraph/msgraph-beta-sdk-java
Go https://github.com/microsoftgraph/msgraph-sdk-go https://github.com/microsoftgraph/msgraph-beta-sdk-go
PHP https://github.com/microsoftgraph/msgraph-sdk-php https://github.com/microsoftgraph/msgraph-beta-sdk-php
Python https://github.com/microsoftgraph/msgraph-sdk-python https://github.com/microsoftgraph/msgraph-beta-sdk-python
Ruby https://github.com/microsoftgraph/msgraph-sdk-ruby https://github.com/microsoftgraph/msgraph-beta-sdk-ruby

Very often, developers need only a small subset of the Microsoft Graph APIs, they want to minimize the size of the binaries or test new APIs.

In these cases it's beneficial to use a generated client instead of the SDK. For that purpose, Microsoft provides Kiota tool which stands behind SDKs.

Kiota

Kiota is a command line tool for generating an API client to call any API that exposes OpenAPI description.

Generated clients are compatible with the Microsoft Graph core library portion of the Microsoft-published SDK, so you can add a dependency to the core library if you need to use features such as the page iterator, batch requests, or large file uploads.

On the other hand, you take the responsibility that the generated custom client code will reflect the latest changes in the Graph API.

Install Kiota

dotnet tool install --global Microsoft.OpenApi.Kiota

Commands

Command Description
generate Generates a REST HTTP API client from an OpenAPI description file.
search <searchTerm> Searches for an OpenAPI description in multiple registries.
download <key> Downloads an OpenAPI description from multiple registries.
show Displays the API tree in a given description.
info Displays information about the languages supported by Kiota and dependencies to add in your project.
update Updates existing clients under the target directory using their lock files.
login Logs in to the Kiota registries so search/download/show/generate commands can access private API definitions.
logout Logs out of Kiota registries.

Let's focus on generate command.

Generate command

The generate command itself has the following options

--openapi <path>

The path or URI to the OpenAPI description file used to generate the code files. Mandatory.

--output <path>

The output directory path for the generated code files.

Default value ./output.

--language

The target language for the generated code files. Mandatory.

The possible values are CLI, CSharp, Go, Java, PHP, Python, Ruby, Swift and TypeScript.

--class-name <name>

The class name to use for the core client class.

Default value ApiClient.

--namespace-name <name>

The namespace to use for the core client class.

Default value ApiSdk.

--log-level

The log level to use when logging messages to the main output.

The possible values are Critical, Debug, Error, Information, None, Trace and Warning.

Default value Warning.

--backing-store

Enables backing store for models. Default implementation stores information in a map/dictionary in memory that enables for dirty tracking of changes on a model and reuse of models.

Default value False.

--exclude-backward-compatible

Excludes backward compatible and obsolete assets from the generated result. Should be used for new clients.

Default value False.

--additional-data

Will include the 'AdditionalData' property for models.

Default value True.

--serializer <classes>

The fully qualified class names for serializers. More details

Based on the defined serializer, your app will be able to handle

  • text/plain payloads
  • application/json payloads
  • application/x-www-form-urlencoded payloads
  • multipart/form-data payloads

By default, all mentioned payloads are handled.

--deserializer <classes>

The fully qualified class names for deserializers. More details

Based on the defined serializer, your app will be able to handle

  • text/plain payloads
  • application/json payloads
  • application/x-www-form-urlencoded payloads

By default, all mentioned payloads are handled.

--clean-output

Removes all files from the output directory before generating the code files.

Default value False.

--include-path <include-path>

The paths to include to the generated client. Glob patterns accepted. Append #OPERATION to the pattern to specify the operation to include.

--exclude-path <exclude-path>

The paths to exclude from the generated client. Glob patterns accepted. Append #OPERATION to the pattern to specify the operation to exclude.

--disable-validation-rules

The OpenAPI description validation rules to disable. More details

--clear-cache

Clears any cached data for the current command.

Default value False.

The --include-path and --exclude-path options support glob pattern. A few examples:

  • /me : includes/excludes operations defined on /me endpoint
  • /me/* : includes/excludes endpoints defined on /me endpoint, but not recoursive. /me/messages, me/calendars
  • /me/** : includes/excludes endpoints defined on /me endpoint, recoursively. /me/messages, /me/messages/{messageId}

Generate customized client

The main prerequisite to generate a customized client for the Microsoft Graph API is an OpenAPI description.

OpenAPI descriptions can be downloaded here:

The size of OpenAPI description is almost 30MB for v1.0 and 55MB for beta, so I would recommend to store them locally. Both OpenAPI descriptions are updated once a week.

Example 1

Generate a C# client that access Sites API. The client name will be SitesClient with the default namespace Microsoft.Graph.

kiota generate `
--openapi "C:\\Temp\\Kiota\\v1.0\\openapi.yaml" `
--output "C:\\Temp\\Kiota\\v1.0\\Generated" `
--language CSharp `
--class-name SitesClient `
--namespace-name "Microsoft.Graph" `
--include-path "/sites" `
--include-path "/sites/**" 

--include-path "/sites" will ensure that the code for GET /sites is generated.

Example 2

Generate a C# client that access administrative units API. The client name will be AdministrativeUnitClient with the default namespace Microsoft.Graph.

kiota generate `
--openapi "C:\\Temp\\Kiota\\v1.0\\openapi.yaml" `
--output "C:\\Temp\\Kiota\\v1.0\\Generated" `
--language CSharp `
--class-name AdministrativeUnitClient `
--namespace-name "Microsoft.Graph" `
--include-path "/directory/administrativeUnits" `
--include-path "/directory/administrativeUnits/**" 

Similar to the previous example, --include-path "/directory/administrativeUnits" will ensure that the code for GET /directory/administrativeUnits and POST /directory/administrativeUnits is generated.

Example 3

Generate a C# client that access administrative units API, but exclude all DELETE operations. The client name will be AdministrativeUnitClient with the default namespace Microsoft.Graph.

kiota generate `
--openapi "C:\\Temp\\Kiota\\v1.0\\openapi.yaml" `
--output "C:\\Temp\\Kiota\\v1.0\\Generated" `
--language CSharp `
--class-name AdministrativeUnitClient `
--namespace-name "Microsoft.Graph" `
--include-path "/directory/administrativeUnits" `
--include-path "/directory/administrativeUnits/**#GET" `
--include-path "/directory/administrativeUnits/**#POST" `
--include-path "/directory/administrativeUnits/**#PATCH" `
--include-path "/directory/administrativeUnits/**#PUT"

If you want to exclude all DELETE operations, you need to explicitly specifiy GET, POST, PATCH and PUT in the --include-path option, because more straightforward solution using --include-path "/directory/administrativeUnits/**" and --exclude-path "/directory/administrativeUnits/**#DELETE" is currently not supported by Kiota.

Example 4

Generate a C# client for Workbook API. The client name will be ExcelClient with the default namespace Microsoft.Graph.

kiota generate `
--openapi "C:\\Temp\\Kiota\\v1.0\\openapi.yaml" `
--output "C:\\Temp\\Kiota\\v1.0\\Generated" `
--language CSharp `
--class-name ExcelClient `
--namespace-name "Microsoft.Graph" `
--include-path "**/workbook/**"

Example 5

Generate a C# client for Workbook API, but exclude all endpoints for executing Excel functions. The client name will be ExcelClient with the default namespace Microsoft.Graph.

kiota generate `
--openapi "C:\\Temp\\Kiota\\v1.0\\openapi.yaml" `
--output "C:\\Temp\\Kiota\\v1.0\\Generated" `
--language CSharp `
--class-name ExcelClient `
--namespace-name "Microsoft.Graph" `
--include-path "**/workbook/**" `
--exclude-path "**/workbook/**/functions/**" `
--exclude-path "**/workbook/**/functions"

Conclusion

Using Kiota tool you can quickly generate customized Graph client and reduce size and complexity of the generated code. When referencing the core library, you can still enhance your work by using retry handlers, redirects, etc.

0
Buy Me a Coffee at ko-fi.com
An error has occurred. This application may no longer respond until reloaded. Reload x