SharePoint でリモートタイマージョブを作成する

SharePoint データでアクションを監視および実行することにより、SharePoint を管理するリモートタイマージョブを作成します。リモートタイマージョブは、SharePoint サーバー以外のサーバーで動作するスケジュールされたタスクです。

タイマージョブの使用例を以下に示します。

ガバナンスタスクの実行。特定の条件が満たされない場合にサイトにメッセージを表示したり、保持ポリシーを適用したりします。
プロセッサ集約的なスケジュールされたプロセスの実行。

はじめに

開始するには、GitHub の Microsoft 365 Developer Patterns and Practices プロジェクトから Core.TimerJobs.Samples サンプルアドインをダウンロードします。

注:

この記事で提供されるコードは、明示または黙示のいかなる種類の保証なしに現状のまま提供されるものであり、特定目的への適合性、商品性、権利侵害の不存在についての暗黙的な保証は一切ありません。

Core.TimerJobs.Samples ソリューションの使用を開始するには、Core.TimerJobs.Samples.SimpleJob のショートカットメニュー (右クリック) を開いて [スタートアッププロジェクトに設定] を選択することにより、スタートアッププロジェクト (SimpleJob プロジェクトなど) を選択する必要があります。

注:

Visual Studio に新しいプロジェクトを作成するとき、新しいリモートタイマージョブのビルドを開始するには、OfficeDevPnP.Core NuGet パッケージをプロジェクトに追加します。 Visual Studio で、[ツール]>[NuGet パッケージマネージャー]>[ソリューションの Nuget パッケージの管理] を選択します。

注:

OfficeDevPnP.Core は非推奨となりました。新しいプロジェクトの場合は、代わりに PnP Core SDK を使用します。

リモートタイマージョブをスケジュールする

タイマージョブは、1 回実行するようにスケジュールすることも、定期的なジョブとすることもできます。運用環境でリモートタイマージョブをスケジュールするには、コードを .exe ファイルにコンパイルしてから、Windows Task Scheduler または Microsoft Azure WebJob を使用して .exe ファイルを実行する必要があります。詳細については、「タイマージョブの展開オプション」を参照してください。

Core.TimerJobs.Samples.SimpleJob アドインを使用する

Core.TimerJobs.Samples.SimpleJob で、Program.cs の Main は以下の手順を実行します。

OfficeDevPnP.Core.Framework.TimerJobs.TimerJob 基本クラスから継承する SimpleJob オブジェクトを作成します。
TimerJob.UseOffice365Authentication を使用してタイマージョブを実行するときに使用する Microsoft 365 ユーザー資格情報を設定します。ユーザー資格情報には、サイトコレクションに対する適切なアクセス権限がなければなりません。詳しくは、「認証」を参照してください。
TimerJob.AddSite を使用することにより、タイマージョブがタスクを実行する必要のあるサイトを追加します。オプションとして、TimerJob.AddSite ステートメントを繰り返して複数のサイトを追加することも、ワイルドカード文字 * を使用して特定の URL 下にすべてのサイトを追加することもできます。たとえば、https://contoso.sharepoint.com/sites/* は、sites 管理パスの下のすべてのサイトでタイマージョブを実行します。
PrintJobSettingsAndRunJob を使用してタイマージョブの情報を印刷し、タイマージョブを実行します。

static void Main(string[] args)
{
  SimpleJob simpleJob = new SimpleJob();

  // The user credentials must have access to the site collections you supply.
  simpleJob.UseOffice365Authentication(User, Password);

  // Use the following code if you are using SharePoint Server on-premises.
  //simpleJob.UseNetworkCredentialsAuthentication(User, Password, Domain);

  // Add one or more sites that the timer job should work with.
  simpleJob.AddSite("https://contoso.sharepoint.com/sites/dev");

  // Prints timer job information and then calls Run().
  PrintJobSettingsAndRunJob(simpleJob);
}

simpleJob オブジェクトがインスタンス化されると、SimpleJob コンストラクターは以下を行います。

TimerJob 基本クラスのコンストラクターを呼び出します。
TimerJobRun イベントを処理するSimpleJob_TimerJobRun イベントハンドラーを割り当てます。 SimpleJob_TimerJobRun は、 TimerJob.Run への呼び出しが行われたときに実行されます。これについては、この記事の後半で詳しく説明します。

public SimpleJob() : base("SimpleJob")
{
  TimerJobRun += SimpleJob_TimerJobRun;
}

PrintJobSettingsAndRunJob が実行されると、TimerJob からの出力がコンソールウィンドウに書き込まれて、TimerJob.Run が呼び出されます。

private static void PrintJobSettingsAndRunJob(TimerJob job)
{
  Console.ForegroundColor = ConsoleColor.Yellow;
  Console.WriteLine("************************************************");
  Console.WriteLine("Job name: {0}", job.Name);
  Console.WriteLine("Job version: {0}", job.Version);
  Console.WriteLine("Use threading: {0}", job.UseThreading);
  Console.WriteLine("Maximum threads: {0}", job.MaximumThreads);
  Console.WriteLine("Expand sub sites: {0}", job.ExpandSubSites);
  Console.WriteLine("Authentication type: {0}", job.AuthenticationType);
  Console.WriteLine("Manage state: {0}", job.ManageState);
  Console.WriteLine("SharePoint version: {0}", job.SharePointVersion);
  Console.WriteLine("************************************************");
  Console.ForegroundColor = ConsoleColor.Gray;

  // Run job.
  job.Run();
}

TimerJob.Run は、TimerJobRun イベントを発生させます。 TimerJob.Run は、TimerJobRun イベントを処理するイベントハンドラーとして SimpleJob のコンストラクターに設定した SimpleJob.cs の SimpleJob_TimerJobRun を呼び出します。

SimpleJob_TimerJobRun で、タイマージョブの実行時にタイマージョブが実行するカスタムコードを追加できます。 SimpleJob_TimerJobRun は、Program.csで TimerJob.AddSite を使用して追加したサイトでカスタムコードを実行します。

このコードサンプルでは、SimpleJob_TimerJobRun が ClientContext を TimerJob から使用して、サイトのタイトルをコンソールウィンドウに書き込みます。 TimerJob.AddSite を使用して複数のサイトが追加された場合、サイトごとにSimpleJob_TimerJobRunが呼び出されます。

void SimpleJob_TimerJobRun(object sender, TimerJobRunEventArgs e)
{
  e.WebClientContext.Load(e.WebClientContext.Web, p => p.Title);
  e.WebClientContext.ExecuteQueryRetry();
  Console.WriteLine("Site {0} has title {1}", e.Url, e.WebClientContext.Web.Title);
}

例: コンテンツタイプの保持を適用するタイマージョブ

Core.TimerJobs.Samples.ContentTypeRetentionEnforcementJob プロジェクトは、SharePoint タイマージョブを使用してコンテンツタイプに保持ポリシーを適用する方法を示しています。 app.config で ContentTypeRetentionPolicyPeriod 要素を使用して、次のように指定します。

key、これは保持期間が適用されるコンテンツタイプ用のコンテンツタイプ ID です。
value、これは保持期間の日数です。保持期間は、key で指定されたコンテンツタイプを使用して作成されたすべてのリスト項目に適用されます。

<ContentTypeRetentionPolicyPeriod>
  <!-- Key is the content type ID, and value is the retention period in days -->
  <!-- Specifies an audio content type should be kept for 183 days -->
  <add key="0x0101009148F5A04DDD49cbA7127AADA5FB792B006973ACD696DC4858A76371B2FB2F439A" value="183" />
  <!-- Specifies a document content type should be kept for 365 days -->
  <add key="0x0101" value="365" />
</ContentTypeRetentionPolicyPeriod>

ContentTypeRetentionEnforcementJob_TimerJobRun は、 TimerJobRun イベントのイベントハンドラーとして設定されています。 Program.csで TimerJob.Run が呼び出されると、 ContentTypeRetentionEnforcementJob_TimerJobRunは、Program.cs で TimerJob.AddSite を使用して追加された各サイトで次の手順を実行します。

サイト上のすべてのドキュメントライブラリを取得します。
サイト上の各ドキュメントライブラリで、app.config の ContentTypeRetentionPolicyPeriod で指定されたすべての構成情報を読み取ります。app.config から読み取られるコンテンツタイプ ID と保持期間のペアごとに、ApplyRetentionPolicy が呼び出されます。

void ContentTypeRetentionEnforcementJob_TimerJobRun(object sender, TimerJobRunEventArgs e)
{
  try
  {
    Log.Info("ContentTypeRetentionEnforcementJob", "Scanning web {0}", e.Url);

    // Get all document libraries. Lists are excluded.
    var documentLibraries = GetAllDocumentLibrariesInWeb(e.WebClientContext, e.WebClientContext.Web);

    // Iterate through all document libraries.
    foreach (var documentLibrary in documentLibraries)
    {
      Log.Info("ContentTypeRetentionEnforcementJob", "Scanning library {0}", documentLibrary.Title);

      // Iterate through configured content type retention policies specified in app.config.
      foreach (var contentTypeName in configContentTypeRetentionPolicyPeriods.Keys)
      {
        var retentionPeriods = configContentTypeRetentionPolicyPeriods.GetValues(contentTypeName as string);
        if (retentionPeriods != null)
        {
          var retentionPeriod = int.Parse(retentionPeriods[0]);
          ApplyRetentionPolicy(e.WebClientContext, documentLibrary, contentTypeName, retentionPeriod);
        }
      }
    }
  }
  catch(Exception ex)
  {
    Log.Error("ContentTypeRetentionEnforcementJob", "Exception processing site {0}. Exception is {1}", e.Url, ex.Message);
  }
}

ApplyRetentionPolicy は、以下の方法でカスタムの保持ポリシーアクションを適用します。

validationDate を計算します。 ApplyRetentionPolicy メソッドは、validationDate より前に変更されたドキュメントに保持ポリシーアクションを適用します。その後で、validationDate が CAML 日付として書式設定され、camlDate に割り当てられます。
CAML クエリを実行して、app.config で指定されたコンテンツタイプ ID に基づいて、ドキュメントライブラリ内のドキュメントをフィルター処理します。[変更日時] の日付が camlDate より小さくなるようにします。
リスト項目ごとに、カスタムコードを使用してドキュメントに対して実行するカスタム保持アクションを適用します。

private void ApplyRetentionPolicy(ClientContext clientContext, List documentLibrary, object contentTypeId, int retentionPeriodDays)
{
  // Calculate validation date. You need to enforce the retention policy on any document modified before validation date.
  var validationDate = DateTime.Now.AddDays(-retentionPeriodDays);
  var camlDate = validationDate.ToString("yyyy-MM-ddTHH:mm:ssZ");

  // Get old documents in the library that match the content type.
  if (documentLibrary.ItemCount > 0)
  {
    var camlQuery = new CamlQuery();

    camlQuery.ViewXml = String.Format(
      @"<View>
        <Query>
          <Where>
            <And>
              <BeginsWith><FieldRef Name='ContentTypeId'/><Value Type='ContentTypeId'>{0}</Value></BeginsWith>
              <Lt><FieldRef Name='Modified' /><Value Type='DateTime'>{1}</Value></Lt>
            </And>
          </Where>
        </Query>
      </View>", contentTypeId, camlDate);

    var listItems = documentLibrary.GetItems(camlQuery);
    clientContext.Load(listItems,
      items => items.Include(
        item => item.Id,
        item => item.DisplayName,
        item => item.ContentType));

    clientContext.ExecuteQueryRetry();

    foreach (var listItem in listItems)
    {
      Log.Info("ContentTypeRetentionEnforcementJob", "Document '{0}' has been modified earlier than {1}. Retention policy will be applied.", listItem.DisplayName, validationDate);
      Console.WriteLine("Document '{0}' has been modified earlier than {1}. Retention policy will be applied.", listItem.DisplayName, validationDate);

      // Apply your custom retention actions here. For example, archiving documents, or starting a disposition workflow.
    }
  }
}

例: ガバナンスタイマージョブ

Core.TimerJobs.Samples.GovernanceJob プロジェクトは、タイマージョブを使用して 2 人の管理者がサイトコレクションに割り当てられていることを確認し、割り当てられていない場合にはサイトに通知メッセージを表示します。

SiteGovernanceJob_TimerJobRun は、 TimerJobRun イベントのイベントハンドラーとして設定されています。 Program.csで TimerJob.Run が呼び出されると、 SiteGovernanceJob_TimerJobRunは、Program.cs で TimerJob.AddSite を使用して追加された各サイトコレクションに対して次の手順を実行します。

OfficeDevPnP.Core の一部である拡張メソッド GetAdministrators を使用して、サイトコレクションに割り当てられている管理者の数を取得します。
OfficeDevPnP.Core の一部である UploadFile を使用して、JavaScript ファイルを SiteAssets またはスタイルライブラリリストにアップロードします。
サイトに割り当てられた管理者が 2 人未満の場合は、JavaScript を使用して、AddJSLink によってサイトに通知メッセージが追加されます。詳しくは、「JavaScript を使用して SharePoint サイト UI をカスタマイズする」を参照してください。
サイトに割り当てられた管理者が 2 人以上の場合は、DeleteJsLink を使用して通知メッセージが削除されます。

void SiteGovernanceJob_TimerJobRun(object o, TimerJobRunEventArgs e)
{
  try
  {
    string library = "";

    // Get the number of administrators.
    var admins = e.WebClientContext.Web.GetAdministrators();

    Log.Info("SiteGovernanceJob", "ThreadID = {2} | Site {0} has {1} administrators.", e.Url, admins.Count, Thread.CurrentThread.ManagedThreadId);

    // Get a reference to the list.
    library = "SiteAssets";
    List list = e.WebClientContext.Web.GetListByUrl(library);

    if (!e.GetProperty("ScriptFileVersion").Equals("1.0", StringComparison.InvariantCultureIgnoreCase))
    {
      if (list == null)
      {
        // Get a reference to the list.
        library = "Style%20Library";
        list = e.WebClientContext.Web.GetListByUrl(library);
      }

      if (list != null)
      {
        // Upload js file to list.
        list.RootFolder.UploadFile("sitegovernance.js", "sitegovernance.js", true);
        e.SetProperty("ScriptFileVersion", "1.0");
      }
    }

    if (admins.Count < 2)
    {
      // Show notification message because you need at least two site collection administrators.
      e.WebClientContext.Site.AddJsLink(SiteGovernanceJobKey, BuildJavaScriptUrl(e.Url, library));
      Console.WriteLine("Site {0} marked as incompliant!", e.Url);
      e.SetProperty("SiteCompliant", "false");
    }
    else
    {
      // Remove the notification message because two administrators are assigned.
      e.WebClientContext.Site.DeleteJsLink(SiteGovernanceJobKey);
      Console.WriteLine("Site {0} is compliant", e.Url);
      e.SetProperty("SiteCompliant", "true");
    }

    e.CurrentRunSuccessful = true;
    e.DeleteProperty("LastError");
  }
  catch(Exception ex)
  {
    Log.Error("SiteGovernanceJob", "Error while processing site {0}. Error = {1}", e.Url, ex.Message);
    e.CurrentRunSuccessful = false;
    e.SetProperty("LastError", ex.Message);
  }
}

SharePoint でリモート タイマー ジョブを作成する

はじめに

リモート タイマー ジョブをスケジュールする

Core.TimerJobs.Samples.SimpleJob アドインを使用する

例: コンテンツ タイプの保持を適用するタイマー ジョブ

例: ガバナンス タイマー ジョブ

関連項目

その他のリソース

SharePoint でリモートタイマージョブを作成する

リモートタイマージョブをスケジュールする

例: コンテンツタイプの保持を適用するタイマージョブ

例: ガバナンスタイマージョブ