Write simpler code with the new Microsoft Graph .NET SDK v5

Maisa Rissi

Using the Microsoft Graph .NET SDK, you can take advantage of a fluent API and models that support retry handling, secure redirects, batching requests, large file management, and many more capabilities. This allows you to focus on what really matters, your business.

Today, we’re announcing the release candidate of Microsoft Graph .NET SDK version 5.0 that includes features to enhance your development experience, described below.

Combine both v1.0 and beta APIs for testing and early adoption

Users should always rely on Microsoft Graph v1.0 when building their application. However, sometimes there is a need to use the Microsoft Graph beta endpoint for testing or early adoption before a feature is available in v1.0. The beta endpoint and the functionality there is still in preview status and can change. This makes the beta endpoints unreliable for production usage since it may break existing scenarios without notice.

So, thinking of that, you can now easily combine both production and preview in any application you might need, using v1.0 as much as possible and beta only where you truly need. You can now combine both v1.0 and beta libraries in one project. This approach offers the benefit of only using preview beta APIs when necessary and relying on stable v1.0 as much as possible.

Get specialized objects with OData cast support

OpenAPI has a way to describe which property can be used as a discriminator on an object type to determine the true type of an object, adding support for polymorphism.

With the OData cast support, SDK users can easily access properties available on a specialized type rather than going through the AdditionalData. OData cast allows downcasting, the result to the right specialized type. This can be exemplified in the Microsoft Graph API by members of a group. It can be either a User, Application, Device, Group and more.

Use more accurate and simplified fluent API and improve code readability

To ease the use of the SDK, the Microsoft Graph .NET v5 simplifies the fluent API to create requests to call Microsoft Graph API, improving the code readability thanks to method chaining and reduces the developer’s learning curve.

1.      Write less error-prone code with better intellisense

Users can now add headers and any query options to customize any request by using the new requestConfiguration modifier. With the new modifier, the accuracy of the intellisense in the SDK was also improved, so you see suggestions only for methods that are actually supported by the underlying API.

2.      Count support available in the request builder

With a new Count functionality, SDK users can simplify extending Microsoft Graph API queries with the $count segment when supported by the API. This applies only for $count as URL segment. The $count as a query string parameter needs to use the new requestConfiguration modifier as exemplified above.

3.      Avoid breaking changes by leveraging parameter objects

APIs are always evolving and adding new functionality. To do so, sometimes it’s necessary to change the parameters accepted by them so that users can leverage everything that an API has to offer. Users can now create a request body and pass it as part of the request method. With this feature, you won’t have to rewrite your code every time there is a change to the parameters of an OData action.

4.      Simplified method chaining

Thinking of improving both the learning curve to SDK users and discoverability of what is supported by the APIs, request methods have been renamed to reflect the actual HTTP method being used, so UpdateAsync has become PatchAsync and AddAsync has become PostAsync. In addition to that, the need to use Request() for every call is now in the past, improving the code readability by making it cleaner.

As an example, let’s look at a post request using v4. 

Now, SDK users can just stick to the point and only have code that means something: 

Backing store

Microsoft Graph .NET SDK v5 now introduces the backing store which allows tracking any changes made to objects. Thanks to the backing store, users can update more efficiently modified objects by minimizing the amount of data sent to the API. This significantly improves the performance of your applications.

That also means null properties will no longer be ignored when they are actually set by the user. This unblocks scenarios like disabling recurrence on an event or removing a mobile phone from a user, when using the SDK.

Remove complexity when handling with collections

Often times, users need to retrieve information from Microsoft Graph. With the new version, the SDK removes complexity when handling with collections by matching the shape of the API response, allowing you to easily retrieve and create a list of objects from the result of the GET operation. And even provides direct access to other properties that may come back, such as @odata.nextLink.

However, some queries against Microsoft Graph return multiple pages of data either due to server-side paging or due to the use of the $top query parameter to specifically limit the page size in a request. For performance reasons or when more than one query request is required to retrieve all the results, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results. The SDK provides a PageIterator class to absorb complexity and help with pagination.

Enhanced error handling

You can now have actionable information when something goes wrong with your requests with the new enhanced error handling. The SDK now throws specific instances of ODataError exceptions that rely on the metadata provided by the API to return valuable details rather than a generic ServiceException that was thrown before in any situation.

Custom authentication flows facilitate token acquisition

Custom flows like DelegateAuthenticationProvider come now with additional configuration so users can focus on the token acquisition and not how the request is authenticated.  In most cases, users will remain as a similar experience from what was offered in previous version.

Next steps

Check out this sample app using the Microsoft Graph .NET SDK v5 that you can run and try to build something. Or access this detailed document that outlines breaking changes, fixes and guides you through the migration that an SDK user might run while upgrading to v5. It also provides examples to implement the new features, helping you quickly take advantage of all the new capabilities.

Add the new SDK to your project by running the following command in the Package Manager Console:

Install-Package Microsoft.Graph -PreRelease

Try out the new version today!

Try out the new version and let us know what you think on GitHub! For questions about the Microsoft Graph API, go to Microsoft Q&A.

Get started with the Microsoft Graph API

Microsoft Graph is a single REST API that unifies data across many Microsoft services under one single endpoint, a powerful tool to build applications that work with data from Office 365 and other Microsoft services.

Learn more about Microsoft Graph SDKs

The SDK includes a set of tools, libraries, and documentation that make it easy to get started building applications that take advantage of the rich data and insights available through Microsoft Graph API.

Start saving time and removing complexity in your code today. Sign up for the Microsoft 365 Developer Program to get a free Microsoft 365 developer subscription and start using .NET to connect to Microsoft Graph. We also recommend that you join our Microsoft 365 Platform community calls and events and get involved with other developers who use Microsoft Graph and build solutions for Microsoft 365.

Here are some resources we have pulled together to help you get started.

  1. Explore our public documentation, where you can find how to install the SDK, authenticate, discover which API a cmdlet is calling and more.
  2. Use the Microsoft Graph Explorer, a tool that lets you make requests and see responses against the Microsoft Graph, and which displays corresponding snippets to requests you make.
  3. Visit the Microsoft Graph Dev Center.

Thank you!

We’d like to thank all the members of the community who have helped us make this release better by reporting issues in GitHub! Keep them coming!


Comments are closed. Login to edit/delete your existing comments

  • Oleg Deribas 0

    How does OData cast works in this example:

    //Fetching the members of a group who are of the type User
    var usersInGroup = await graphServiceClient

    Would this automatically add filter so the query would return only objects of type User? Or it would try to cast everything to type user? I definitely hope for the first, but need to ask just because cast term is used.

    • Philippe SignoretMicrosoft employee 2

      The resulting request will look like this:

      GET https://graph.microsoft.com/v1.0/groups/{id}/members/microsoft.graph.user

      Which will return the first page of direct user members of the group. Members of other types (e.g. group or servicePrincipal) will not be returned.

      This is described in the OData 4.0 spec at https://docs.oasis-open.org/odata/odata/v4.0/cs01/part2-url-conventions/odata-v4.0-cs01-part2-url-conventions.html#_Addressing_Derived_Types:

      Any resource path or path expression identifying a collection of entities or complex type instances can be appended with a path segment containing the qualified name of a type derived from the declared type of the collection. The result will be restricted to instances of the derived type and may be empty.

      (So, to answer your question, the results will be filtered, rather than attempting to convert a non-user into a user.)

      • Joe Lopez 0

        I have an API call that applies a filter to the users returned:

        GET https://graph.microsoft.com/v1.0/groups/{id}/members/microsoft.graph.user?$count=true&$filter=createdDateTime ge 2022-02-28T00:00:00Z

        How would that look using the new SDK v5?

        • Maisa RissiMicrosoft employee 1

          You will need to use the requestConfiguration to apply the query options you need as exemplified here.

          Something along the lines of:

          var usersInGroup = await graphServiceClient
              .GetAsync(rc =>
                  rc.QueryParameters.Count = true;
                  rc.QueryParameters.Filter = "createdDateTime ge 2022-02-28T00:00:00Z";
          • Joe Lopez 0

            Thank you, it was the “rc.QueryParameters.Count = true” part I was missing.

            Another issue we have is with not being able to create a user because their email is in another user’s proxy addresses. It’s currently a read-only collection and we’ve tried other ways without success. Will we ever be able to delete a proxy address using v5?

Feedback usabilla icon