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
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/meendpoint/me/*: includes/excludes endpoints defined on/meendpoint, but not recoursive./me/messages,me/calendars/me/**: includes/excludes endpoints defined on/meendpoint, 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.
