Class TimerJob

Abstract base class for creating timer jobs (background processes) that operate against SharePoint sites. These timer jobs are designed to use the CSOM API and thus can run on any server that can communicate with SharePoint.

Inheritance
System.Object
TimerJob
Namespace: PnP.Framework.TimerJobs
Assembly: PnP.Framework.dll
Syntax
public abstract class TimerJob : object

Constructors

TimerJob(String)

Simpliefied constructor for timer job, version is always set to "1.0"

Declaration
public TimerJob(string name)
Parameters
System.String name

Name of the timer job

TimerJob(String, String)

Simpliefied constructor for timer job, sets given version to timer job

Declaration
public TimerJob(string name, string version)
Parameters
System.String name

Name of the timer job
System.String version

Version of the timer job

TimerJob(String, String, String)

Default constructor for timer job

Declaration
public TimerJob(string name, string version, string configurationData)
Parameters
System.String name

Name of the timer job
System.String version

Version of the timer job
System.String configurationData

Timer job configuration data

Properties

AuthenticationType

Gets the authentication type that the timer job will use. This will be set as part of the UseOffice365Authentication and UseNetworkCredentialsAuthentication methods

Declaration
public AuthenticationType AuthenticationType { get; }
Property Value
AuthenticationType

AzureEnvironment

Azure environment that will be used

Declaration
public AzureEnvironment AzureEnvironment { get; set; }
Property Value
AzureEnvironment

ConfigurationData

Gets or sets additional timer job configuration data

Declaration
public string ConfigurationData { get; set; }
Property Value
System.String

ExcludeOD4B

Does the TimerJob also need to enumerate OD4B site collections

Declaration
public bool ExcludeOD4B { get; set; }
Property Value
System.Boolean

ExpandSubSites

Does the TimerJob need to fire as well for every sub site in the site?

Declaration
public bool ExpandSubSites { get; set; }
Property Value
System.Boolean

IsRunning

Is this timer job running?

Declaration
public bool IsRunning { get; }
Property Value
System.Boolean

ManageState

Gets and sets the state management value: when true the timer job will automatically handle state by storing a json serialized class as a web property bag entry. Default value is false

Declaration
public bool ManageState { get; set; }
Property Value
System.Boolean

MaximumThreads

How many threads can be used by this timer job. Default value is 5.

Declaration
public int MaximumThreads { get; set; }
Property Value
System.Int32

Name

Gets the name of this timer job

Declaration
public string Name { get; }
Property Value
System.String

Realm

Realm will be automatically defined, but there's an option to manually specify it which may be needed when did an override of ResolveAddedSites and specify your sites.

Declaration
public string Realm { get; set; }
Property Value
System.String

SharePointVersion

Gets or sets the SharePoint version. Default value is detected based on the laoded CSOM assembly version, but can be overriden in case you want to for example use v16 assemblies in v15 (on-premises)

Declaration
public int SharePointVersion { get; set; }
Property Value
System.Int32

TenantAdminSite

Option to specify the tenant admin site. For MT this typically is not needed since we can detect the tenant admin site, but for on premises and DvNext this is needed

Declaration
public string TenantAdminSite { get; set; }
Property Value
System.String

UseThreading

Can this timer job use multiple threads. Defaults to true

Declaration
public bool UseThreading { get; set; }
Property Value
System.Boolean

Version

Gets the version of this timer job

Declaration
public string Version { get; }
Property Value
System.String

Methods

AddSite(String)

Adds a site Url or wildcard site Url to the collection of sites that the timer job will process

Declaration
public void AddSite(string site)
Parameters
System.String site

Site Url or wildcard site Url to be processed by the timer job

ClearAddedSites()

Clears the list of added site Url's and/or wildcard site Url's

Declaration
public void ClearAddedSites()

Clone(TimerJob)

Takes over the settings from the passed timer job. Is useful when you run multiple jobs in a row or chain job execution. Settings that are taken over are all the authentication, enumeration settings and SharePointVersion

Declaration
public void Clone(TimerJob job)
Parameters
TimerJob job

TimerJob

CreateClientContext(String)

Creates a ClientContext object based on the set AuthenticationType and the used version of SharePoint

Declaration
protected ClientContext CreateClientContext(string site)
Parameters
System.String site

Site Url to create a ClientContext for
Returns
ClientContext

The created ClientContext object. Returns null if no ClientContext was created

GetAllSubSites(Site)

Gets all sub sites for a given site

Declaration
public IEnumerable<string> GetAllSubSites(Site site)
Parameters
Site site

Site to find all sub site for
Returns
IEnumerable<System.String>

IEnumerable of strings holding the sub site URLs

ResolveAddedSites(List<String>)

Virtual method that can be overriden to control the list of resolved sites

Declaration
public virtual List<string> ResolveAddedSites(List<string> addedSites)
Parameters
List<System.String> addedSites

List of added site Url's and/or wildcard site Url's
Returns
List<System.String>

List of resolved sites

Run()

Triggers the timer job to start running

Declaration
public void Run()

SetEnumerationCredentials(String)

Provides the timer job with the enumeration credentials. For SharePoint on-premises username, password and domain are needed

Declaration
public void SetEnumerationCredentials(string credentialName)
Parameters
System.String credentialName

Name of the credential manager registration

SetEnumerationCredentials(String, SecureString)

Provides the timer job with the enumeration credentials. For Office 365 username and password is sufficient

Declaration
public void SetEnumerationCredentials(string userUPN, SecureString password)
Parameters
System.String userUPN

user name
SecureString password

Password of the enumeration user

SetEnumerationCredentials(String, SecureString, String)

Provides the timer job with the enumeration credentials. For SharePoint on-premises username, password and domain are needed

Declaration
public void SetEnumerationCredentials(string samAccountName, SecureString password, string domain)
Parameters
System.String samAccountName

Account name of the enumeration user
SecureString password

Password of the enumeration user
System.String domain

Domain of the enumeration user

SetEnumerationCredentials(String, String)

Provides the timer job with the enumeration credentials. For Office 365 username and password is sufficient

Declaration
public void SetEnumerationCredentials(string userUPN, string password)
Parameters
System.String userUPN

user name
System.String password

Password of the enumeration user

SetEnumerationCredentials(String, String, String)

Provides the timer job with the enumeration credentials. For SharePoint on-premises username, password and domain are needed

Declaration
public void SetEnumerationCredentials(string samAccountName, string password, string domain)
Parameters
System.String samAccountName

UPN of the enumeration user
System.String password

Password of the enumeration user
System.String domain

Domain of the enumeration user

UpdateAddedSites(List<String>)

Virtual method that can be overriden to allow the timer job itself to control the list of sites to operate against. Scenario is for example timer job that reads this data from a database instead of being fed by the calling program

Declaration
public virtual List<string> UpdateAddedSites(List<string> addedSites)
Parameters
List<System.String> addedSites

List of added site Url's and/or wildcard site Url's
Returns
List<System.String>

List of added site Url's and/or wildcard site Url's

UseAccessTokenAuthentication(String)

Prepares the TimerJob to operate against SharePoint Only with a provided access token. Sets AuthenticationType to AuthenticationType.AccessToken

Declaration
public void UseAccessTokenAuthentication(string accessToken)
Parameters
System.String accessToken

Provided access token

UseAppOnlyAuthentication(String, String)

Prepares the TimerJob to operate against SharePoint on-premises with app-only credentials. Sets AuthenticationType to AuthenticationType.AppOnly

Declaration
public void UseAppOnlyAuthentication(string clientId, string clientSecret)
Parameters
System.String clientId

Client ID of the app
System.String clientSecret

Client Secret of the app

UseAppOnlyAuthentication(String, String, SecureString, String)

Prepares the timerjob to operate against SharePoint on-premises with app-only client Id and certificate in High Trust mode. Sets AuthenticationType to AuthenticationType.AppOnly

Declaration
public void UseAppOnlyAuthentication(string clientId, string certificatePath, SecureString certificatePassword, string certificateIssuerId)
Parameters
System.String clientId

Client ID of the app
System.String certificatePath

Path of the Certificate file
SecureString certificatePassword

Password of the Certificate
System.String certificateIssuerId

The Issuer ID of the certificate

UseAppOnlyAuthentication(String, String, String, String)

Prepares the timerjob to operate against SharePoint on-premises with app-only client Id and certificate in High Trust mode. Sets AuthenticationType to AuthenticationType.AppOnly

Declaration
public void UseAppOnlyAuthentication(string clientId, string certificatePath, string certificatePassword, string certificateIssuerId)
Parameters
System.String clientId

Client ID of the app
System.String certificatePath

Path of the Certificate file
System.String certificatePassword

Password of the Certificate
System.String certificateIssuerId

The Issuer ID of the certificate

UseAzureADAppOnlyAuthentication(String, String, String, SecureString)

Prepares the TimerJob to operate against SharePoint Only with Azure AD app-only credentials. Sets AuthenticationType to AuthenticationType.AzureADAppOnly

Declaration
public void UseAzureADAppOnlyAuthentication(string clientId, string azureTenant, string certificatePath, SecureString certificatePassword)
Parameters
System.String clientId

Client ID of the app
System.String azureTenant

The Azure tenant name, like contoso.com
System.String certificatePath

The path to the *.pfx certicate file
SecureString certificatePassword

The password to the certificate

UseAzureADAppOnlyAuthentication(String, String, String, String)

Prepares the TimerJob to operate against SharePoint Only with Azure AD app-only credentials. Sets AuthenticationType to AuthenticationType.AzureADAppOnly

Declaration
public void UseAzureADAppOnlyAuthentication(string clientId, string azureTenant, string certificatePath, string certificatePassword)
Parameters
System.String clientId

Client ID of the app
System.String azureTenant

The Azure tenant name, like contoso.com
System.String certificatePath

The path to the *.pfx certicate file
System.String certificatePassword

The password to the certificate

UseAzureADAppOnlyAuthentication(String, String, X509Certificate2)

Prepares the TimerJob to operate against SharePoint Only with Azure AD app-only credentials. Sets AuthenticationType to AuthenticationType.AzureADAppOnly

Declaration
public void UseAzureADAppOnlyAuthentication(string clientId, string azureTenant, X509Certificate2 certificate)
Parameters
System.String clientId

Client ID of the app
System.String azureTenant

The Azure tenant name, like contoso.com
X509Certificate2 certificate

The X.509 Certificate to use for AppOnly Authentication

UseOffice365Authentication(String)

Prepares the TimerJob to operate against Office 365 with user and password credentials which are retrieved via the windows Credential Manager. Also sets AuthenticationType to AuthenticationType.Office365

Declaration
public void UseOffice365Authentication(string credentialName)
Parameters
System.String credentialName

Name of the credential manager registration

UseOffice365Authentication(String, SecureString)

Prepares the TimerJob to operate against Office 365 with user and password credentials. Sets AuthenticationType to AuthenticationType.Office365

Declaration
public void UseOffice365Authentication(string userUPN, SecureString password)
Parameters
System.String userUPN

user name
SecureString password

Password of the user that will be used to operate the timer job work

UseOffice365Authentication(String, String)

Prepares the TimerJob to operate against Office 365 with user and password credentials. Sets AuthenticationType to AuthenticationType.Office365

Declaration
public void UseOffice365Authentication(string userUPN, string password)
Parameters
System.String userUPN

user name
System.String password

Password of the user that will be used to operate the timer job work

Events

TimerJobRun

TimerJobRun event

Declaration
public event TimerJobRunHandler TimerJobRun
Event Type
TimerJobRunHandler

Extension Methods