SharePoint Tenant CSOM object support in SharePoint 2013 and 2016

  • [アーティクル]

If you are planning to implement add-in/app model implementations in SharePoint on-premises environment and you’d like to create also site collections with the add-in model techniques, you will need to use Tenant CSOM object for your operations. I wrote a blog post for this back in 2014, which is still absolutely valid for the SharePoint 2013 and also works for the SharePoint 2016 Preview release. Tenant object name could be slightly misleading for the on-premises, but it also works in normal environments where you have not configured the farm to use multi-tenant features.

Note. Only difference for the guidance around SharePoint 2016 is that you’ll need to update version attribute for the server side assembly registration from 15 to 16. Other than that scripts are working properly also in SharePoint 2016 version.

If you are working with SharePoint 2013 version, you should be using 15 version of the CSOM package and tenant assembly (Microsoft.Online.SharePoint.Client.Tenant.dll) is included for example in the SharePoint Server 2013 Client Components SDK package which is downloadable from the MS downloads. Alternatively you could also use the PnP Nuget package targeted for on-premises, which contains correct version automatically.

15 or 16 version of the Tenant object has actually quite a lot of different methods, but not all of these are supported for on-premises deployment even though they do exist even in the 15 version of CSOM, which is specifically targeted for SharePoint 2013. This could be highly confusing, but there are some technical and resourcing reasons behind of releasing an object targeted for on-premises, which has non-supported capabilities.

Here’s the officially supported methods for the CSOM Tenant object for on-premises

  • CreateSite
    • Creates a new site collection based on the information specified by the SiteCreationProperties parameter.
  • GetSiteByUrl
    • Get the Site object for the specified site.
  • SetSiteAdmin
    • Can be used to set or remote account as site collection admin
  • GetDeletedSitePropertiesByUrl 
    • Gets information for a single deleted site
  • RemoveSite 
    • Removes site to recycle bin
  • RestoreDeletedSite 
    • Restores the deleted site collection
  • RemoveDeletedSite 
    • Permanently deletes the site collection from the recycle bin
  • GetSPOTenantWebTemplates 
    • Returns the site collection templates that tenant admin can use to create sites

All other methods of the Tenant object are not supported and will cause for exceptions due dependencies on site subscription, which typically does not exist in the on-premises deployment. Notice also that some of the supported methods do require specific permissions for the account used for the operations, if you do not use oAuth for granting the needed permissions in your on-premises deployment. This applies specifically for the site collection remove and restore operations.

If you are interested on using Tenant object in the on-premises, please follow up the instructions in the following blog post for enabling this capability in your farm. You will need to specifically enable the Tenant object by running a PowerShell script and you’ll need to mark one of your site collections as “Tenant admin” site collection, even though you would not be running in multi-tenant mode, which you should not do in on-premises anyway, but that’s another story.

Office 365 Developer Patterns and Practices

Office365PnPLogoRed_thumb1Techniques showed in this blog post are part of the Office 365 Developer Patterns and Practices guidance, which contains more than 100 samples and solutions demonstrating different patterns and practices related on the add-in/app model development together with additional documentation related on the add-in/app model techniques.

Check the details around PnP from dev.office.com at https://aka.ms/OfficeDevPnP. Please join us on sharing patterns and practices for the community for the benefit of the community. If you have any questions, comments or feedback related on this sample, blog post or anything on PnP, please use the Office 365 Developer Patterns and Practices Yammer group at https://aka.ms/OfficeDevPnPYammer.

“Sharing is caring”

Comments

  • Anonymous
    August 16, 2016
    7b88h
  • Anonymous
    June 02, 2017
    What exactly does "special permissions" mean according to the remove operation: "Notice also that some of the supported methods do require specific permissions for the account used for the operations, if you do not use oAuth for granting the needed permissions in your on-premises deployment. This applies specifically for the site collection remove and restore operations."If I try to remove a site collection, I get an access denied error. Creating a new site collection works.Thanks!