When you are developing your customizations using managed code and with Client Side Object Model (CSOM), it’s important to understand that CSOM version to be used is dependent on your target environment. Since this versioning is not clear in the currently available documentation and we are getting questions around this constantly, we wanted to write this short blog post explaining how the CSOM versioning works and what version you should be using.
CSOM version is dependent on the server side version of the SharePoint. This means that if you are using too new CSOM version, which is newer than SharePoint server side deployment in your environment, you can face challenges. Issues or exceptions are visible if you are trying to use method or a property in newer CSOM version, which is not yet exposed in the server side. This will result typically somewhat following kind of exception message:
An unhandled exception of type 'Microsoft.SharePoint.Client.ServerException' occurred in Microsoft.SharePoint.Client.Runtime.dll
Additional information: Cannot find stub for type with id "{c7e15a67-857e-454b-8913-e1e42fa52ab1}".
The specified server may not support APIs used in this operation.
An unhandled exception of type 'Microsoft.SharePoint.Client.ServerException' occurred in Microsoft.SharePoint.Client.Runtime.dll
Unique identifier (GUID) in this exception is referring to specific missing property or method, which is not yet exposed in the server side for the CSOM to be used. So basically this indicates that you are version mismatch between the CSOM version and the server side SharePoint.
How do CSOM versioning work?
There are two main deployment or versioning models for CSOM – one for on-premises (SP2013 and SP2016) and one for SharePoint Online. This versioning model and relationship on available properties and methods is demonstrated in the following picture.
So what does it mean in practice? – Let’s go through the different models and recommended CSOM version between on-premises and SharePoint Online.
On-premises
We do not currently release Nuget Gallery packages for SharePoint on-premises, so you will either need to use CSOM versions available from Microsoft Download center or alternatively using CSOM assemblies available from the ISAPI folder at the SharePoint server. We are looking into releasing on-premises CSOM versions of the assemblies also using Nuget Gallery in future, so that you can align your code to any specific CU.
SharePoint 2016 has been just released, so there’s only one CSOM version available for it. You can find the right assemblies from Microsoft Download Center from following location:
SharePoint 2013 has also SDK setup available from Microsoft Download center, which aligns with the April 2015 CU for SharePoint 2013. This means that if you are using older SharePoint version in your server side, you can potentially run into issues.
It’s important to realize that if you will need to take advantage of some properties or methods in on-premises which are newer than the released SDKs, you will need to reference assemblies available directly from the ISAPI folder. When you will do this, you will have a dependency on than particular SharePoint server side version.
In general, when you do development towards on-premises, you will need to decide a baseline CU requirement, which your on-premises customization will support. We do understand that this is not really optimal, but there’s currently really no other options due the versioning model for the on-premises. You can also potentially build multiple different versions of your product based on the target environment. This model is for example used with Office 365 Dev PnP Core Component, where which uses only one code base, but can be compiled towards numerous target environments.
SharePoint Online
Since SharePoint Online server side version is controlled by Microsoft, we can also control the recommended and released CSOM package for SharePoint Online. This means that we can deploy always a new version of the SharePoint Online CSOM when Office 365 tenants worldwide have been properly updated with the matching server side version. There’s two methods of getting access on the SharePoint Online CSOM:
- Use Microsoft.SharePointOnline.CSOM Nuget package from Nuget Gallery
- Download SharePoint Online Client Component SDK from Microsoft Download
We recommend usage of the Nuget package, which has numerous advantages and is updated much more frequently than the downloadable SDK. If you want to take advantage of the latest CSOM capabilities for SharePoint Online, you should be using the Nuget package and check the latest release notes around the new versions from the dev.office.com blog.
Questions and Answers
I have tested SPO CSOM to on-premises and it works, why is that?
It works fine unless you will use properties or methods which are not exposed in the on-premises. If you can guarantee that your code does not touch properties which have not been enabled in on-premises version, you can theoretically use SharePoint Online CSOM with on-premises as well. We do however recommend on using right CSOM version for specific server side version to avoid issues.
There was some CSOM properties in the SPO CSOM Nuget, which did not work even though they were included – why?
Some of the new capabilities which are included in the CSOM assemblies are not available in the tenants until those are specifically enabled. Good example of this kind of capability was Bulk UPA Custom Profile Properties Update API, which was already included in the December 2015 release of the SPO CSOM nuget package, but the server side capability was enabled April 2016.
SharePoint 2016 was said to use same bits as SharePoint Online, why CSOM is different?
SharePoint 2016 is based on the same code base as SharePoint Online, but to a different fork. There are numerous different capabilities which are only relevant or available in general in the SharePoint Online.
Why is some properties and methods only added to SharePoint Online CSOM and not to on-premises?
In some cases, this is due the fact that capability only makes sense for SharePoint Online and in some cases we are just updating the SharePoint Online faster than on-premises. On-premises CSOM and related server side changes are much harder to test, due the possible environmental differences between individual deployments. Our target is to get all relevant CSOM changes also back-ported to the on-premises CSOM versions, but this is not always guaranteed or possible due resource constraints.
Why can’t we just release one set of APIs and use that cross all environments – Having three different CSOM packages is confusing?
This is understandable comment, but the requirement to have currently three different versions of CSOM API is really coming from the fact that we have three different main server side versions and if we want to expose also new APIs with newer versions, we will need to have a support for that in the CSOM side. Obviously this would not be an issues if we would only expose RESTful APIs from SharePoint, but based on community input, usage of the CSOM is easier and more productive, especially for the developers with SharePoint server side development background.
If you have any additional questions, comments or feedback around information in this blog post, please use the Office Dev Patterns and Practices Yammer group at http://aka.ms/OfficeDevPnPYammer.
“Sharing is caring”
Vesa Juvonen, Senior Program Manager, Office 365, Microsoft – 13th of April 2016
