SharePoint site theming: CSOM development
The SharePoint client-side object model (CSOM) provides access to the SharePoint object model from code that is running locally or on a different server than SharePoint.
Prerequisites
Before you get started, make sure that you're familiar with the following:
You also need to reference the Microsoft.SharePointOnline.CSOM NuGet package (version 16.1.6906.1200 or later).
CSOM code example
The following example shows how to create a Microsoft.Online.SharePoint.TenantAdministration.Tenant object and call the GetAllTenantThemes method to return a list of themes.
Note
- The URL used to create the context object includes the -admin suffix because TenantAdministration methods work with the admin site.
- Create a Tenant instance with the Tenant constructor, and then call the methods on that instance.
- You can use the same approach to call other theme management methods.
using System.Security;
using Microsoft.SharePoint.Client;
using Microsoft.Online.SharePoint.TenantAdministration;
using Microsoft.Online.SharePoint.TenantManagement;
...
ClientContext ctx = new ClientContext("https://mysite-admin.sharepoint.com/");
var pwd = "mypassword";
var passWord = new SecureString();
foreach (char c in pwd.ToCharArray()) passWord.AppendChar(c);
ctx.Credentials = new SharePointOnlineCredentials("admin@mydomain.com", passWord);
Tenant tenant = new Tenant(ctx);
ClientObjectList<ThemeProperties> themes = tenant.GetAllTenantThemes();
Theme definition example
For methods that take a theme argument, the following code defines an SPOTheme class that you can use to create custom themes.
/// <summary>
/// Properties defining a theme in SharePoint Online.
/// </summary>
public class SPOTheme
{
/// <summary>
/// Specifies the name of the theme. This must uniquely identify the theme.
/// </summary>
public string Name
{
get; private set;
}
/// <summary>
/// Specifies the palette of colors in the theme, as a dictionary of theme slot values.
/// </summary>
public IDictionary<String, String> Palette
{
get; private set;
}
/// <summary>
/// Specifies whether the theme is inverted, with a dark background and a light foreground.
/// </summary>
public bool IsInverted
{
get; private set;
}
}
Applying a theme
There's currently no supported CSOM API to programmatically apply a theme to a specific site. For information on applying custom themes to individual site collections see SharePoint site design and site script overview
Methods/properties of the Microsoft.Online.SharePoint.TenantAdministration.Tenant class
Use the following methods to customize the set of available themes for a SharePoint tenant administration site. You can add a new custom theme, update an existing theme, or delete a theme, and you can retrieve a specific theme or all themes. You can also hide or restore the default themes that come with SharePoint.
AddTenantTheme public method
Add a theme to the tenant.
Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name, string themeJson
Return type: ClientResult<bool>
DeleteTenantTheme public method
Delete a theme from the tenant.
Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name
Return type: void
GetAllTenantThemes public method
Retrieve all the themes that are currently available in the tenant, including any custom themes that have been added. Default themes are only included if the HideDefaultThemes property is false (the default value).
Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: none
Return type: ClientObjectList<ThemeProperties>
GetTenantTheme public method
Retrieve a theme by name.
Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name
Return type: ThemeProperties
HideDefaultThemes public property
This property indicates whether the default themes are available in the theme picker UI. The default setting is false (the default themes are available), but you might want to set this property to true after you define custom themes, to allow only specific themes to be used.
Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Type: Boolean
UpdateTenantTheme public method
Update the settings for an existing theme.
Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name, string themeJson
Return type: ClientResult<bool>
Methods of the Microsoft.Online.SharePoint.TenantManagement.Tenant class
These are alternative APIs to manage your themes at the tenant level.
AddTenantTheme public method
Add a theme to the tenant.
Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: string name, string themeJson
Return type: ClientResult<bool>
GetAllTenantThemes public method
Retrieve all the themes that are currently available in the tenant, including any custom themes that have been added. Default themes are only included if the HideDefaultThemes property is false (the default value).
Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: none
Return type: ClientObjectList<ThemeProperties>
GetHideDefaultThemes public method
Read the current setting for whether to hide default themes in the theme picker UI.
Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: none
Return type: ClientResult<bool>
GetTenantTheme public method
Retrieve a theme by name.
Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: string name
Return type: ThemeProperties
SetHideDefaultThemes public method
Specify whether to hide default themes in the theme picker UI.
Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: Boolean
Return type: void
UpdateTenantTheme public method
Update the settings for an existing theme.
Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: string name, string themeJson
Return type: ClientResult<bool>