Microsoft Graph .NET SDK updates
It has been a while since the Microsoft Graph SDK team provided an update and customers have been asking us when the next update will be available. It is great to hear that people care! These updates took a longer to deliver than we planned as we made a few bolder steps towards our longer-term plans, and we had a few hiccups along the way.
Service library vs core library
For all of our SDKs, we’ve been moving toward a deployment model where SDKs come in two types of packages: service libraries and a core library. A service library contains the models and request builders generated from a specific version of the Microsoft Graph metadata. The core library provides the infrastructure to make reliable and resilient HTTP requests to Microsoft Graph.
The split is necessary and useful for a few reasons. Microsoft Graph metadata is updated weekly as new features are added. Our goal for this year is to be able to update the service library packages within a week of the metadata updates. This means that the process to release the service libraries is going to be highly automated, the version numbers are going to go high, and there won’t be preview releases of these service libraries between minor version releases. Service libraries are a little confusing because they have a version number, but that version number is not related to the Microsoft Graph API version. Currently, there is a Microsoft.Graph package, which supports Microsoft Graph v1.0, and a Microsoft.Graph.Beta package that supports the Microsoft Graph beta API.
The core library will release on a much slower cadence and there will be preview releases. This library will work with all the service libraries. Or stated differently, the core library can be used to call any version of the Microsoft Graph API. Over time, the core library will contain all the handwritten code, and the service library will only contain generated code. We are not quite there yet, but this will enable us to do more really cool stuff.
Azure SDK alignment
Recently, more developers have started to take advantage of the features available in both Microsoft Graph and Azure. This has led us to work more closely with the Azure SDK team to ensure that the Azure and Microsoft Graph SDKs will work together seamlessly. We all know the challenges of mismatched dependent assemblies. We also recognized that we were building similar but different mechanisms to get authorization tokens. We are working to improve that experience.
Breaking SDK update
The Microsoft Graph versioning policy guarantees that there will be no breaking changes. The policy describes what is considered a breaking change, but when you get down to details, there is still room for interpretation. The intent of our versioning policy is less ambiguous. We are committed to ensuring that changes to the Microsoft Graph API will not negatively impact deployed applications.
Recently, there were a number of changes to the API that do not cause deployed applications to fail, but do change the generated service library in such a way as to potentially cause compilation errors when an existing application is updated to a new version of the SDK. For this reason you will see that the major version number of the service library for Microsoft Graph v1.0 has changed. This is the first time it has happened, and hopefully it will remain a rare occurrence.
.NET SDK v1.0 service library v3.0.0 updates
The microsoft.graph Nuget package has moved from v1.21.0 to v3.0.0. You may be wondering what happened to v2.0.0. Believe it or not, we are attempting to avoid confusion. There has been quite a bit of talk about the Microsoft Graph v2.0 and we do not want anyone to assume that this NuGet package version corresponds to the Microsoft Graph API version. The NuGet package version is not related to the Microsoft Graph API version. We have a different NuGet package for each Microsoft Graph API version.
The following changes to the service library might cause your compiler to complain:
- A new property creationType on the organization entity was added in the last release of the SDK. Unfortunately, that property should have been created on user. The property has now been moved. It is unlikely that any client applications have taken a dependency on this property, but there is a small chance that it will cause a compiler error for some.
- More significantly, a number of Teams–related requests now will return the team type and not the group type. The properties in the HTTP payload were only properties that are present in both types and therefore the message on-the-wire does not change in anyway. However, from the compiler’s perspective, these are unrelated types and applications that currently assign the results of these Teams calls to a group object will see compiler errors on updating the service library package. You simply need to change the declared type from group to team.
Because we need to make a breaking change to this library, we are going to take this opportunity to bump the framework requirements to .NET Standard 2.0 and .NET 4.6. Support for .NET Core 1.x ended in June 2019; at that time, we recommended that all users migrate their applications to supported versions of the .NET Framework.
.NET SDK beta service library v0.13.0 preview updates
We are refreshing our beta service library with the latest updates. We are going to break the semantic versioning rules with this SDK version. There will be regular breaking changes to the API in beta and we would like to keep the major version set at 0 as a reminder that this library is a preview and is not recommended for production. For each release, we will update the minor version number. We don’t expect to release patch updates to this library.
You can see the changes that will be in this release in the Microsoft Graph changelog. To be consistent with the v1.0 service library, we will also be changing the framework requirements to.NET 4.6 and .NET Standard 2.0.
.NET SDK core library v2.0 preview
Finally, we have released an early preview of the next major version of our .NET core library. We have been accumulating a list of issues that we want to fix, but require making a new major release.
The most significant changes in this update include:
- Taking a dependency on Azure.Identity and MSAL.NET so that users will get an authentication solution, out of the box and one that is consistent with the experience used with Azure SDKs.
- Moving from Newtonsoft.JSON to System.Text.Json. This will provide performance benefits for those working on .NET Core 3 and will align our dependencies with the Azure SDK team. It will also ensure that there won’t be conflicts with other versions of Newtonsoft.JSON in use across all applications that use the .NET SDK core library.
We will be taking this opportunity to bump up the requirement for the libraries to use either .NET Standard 2.0, or .NET 4.6.
Summary
We’re working hard to make the experience of building applications for Microsoft Graph as easy as possible. We continue to listen to your feedback and encourage you to keep it coming. Our goal is to be as transparent as possible with our efforts. By working together, we can all build great solutions that empower our customers.
Light
Dark