PnP タイマージョブフレームワーク

[アーティクル]
04/08/2023

PnP タイマージョブフレームワークは、SharePoint サイトに対して動作するバックグラウンドプロセスの作成を容易にするために設計されたクラスのセットです。タイマージョブフレームワークは、オンプレミスの完全信頼コードタイマージョブ (SPJobDefinition) に似ています。タイマージョブフレームワークと完全信頼コードタイマージョブの主な相違点は、タイマージョブフレームワークはクライアント側 API のみを使用するため、SharePoint の外部で実行できる (かつ実行する必要がある) ことです。タイマージョブフレームワークを使用することで、SharePoint Online に対して動作するタイマージョブの作成が可能になります。

タイマージョブを作成したら、スケジュールを設定して実行する必要があります。 2 つの最も一般的なオプションは、次のとおりです。

ホスティングプラットフォームが Microsoft Azure の場合、タイマージョブを Azure WebJobs として展開して実行できます。
ホスティングプラットフォームが Windows Server の場合 (オンプレミスの SharePoint の場合など)、タイマージョブは Windows スケジューラで展開して実行できます。

タイマージョブの概要については、「PnP タイマージョブフレームワークの概要」というビデオを参照してください。このビデオでは、タイマージョブフレームワークを紹介し、タイマージョブの単純な例を示します。

タイマージョブの単純な例

このセクションでは、非常に単純なタイマージョブを作成する方法を示します。このサンプルの目的は読者にクイックビューを提供することです。タイマージョブフレームワークの詳細な説明については後述します。

注:

「Hello world」サンプルから実際のコンテンツ有効期限ジョブまで、10 種類のタイマージョブの例を使用した、より広範な PnP ソリューションについては、「Core.TimerJobs.Samples」を参照してください。

以降の手順で、単純なタイマージョブを作成する方法を示します。

手順 1: コンソールプロジェクトを作成し、PnP コアを参照する

「コンソール」タイプの新しいプロジェクトを作成し、次のいずれかの方法で PnP コアライブラリを参照します。

Office 365 Developer パターンおよびプラクティスのコア Nuget パッケージをプロジェクトに追加します。 v15 (オンプレミス) 用と v16 (Office 365) 用の Nuget パッケージがあります。これは優先オプションです。
既存の PnP コアソースプロジェクトを自分のプロジェクトに追加します。これにより、デバッグ時に PnP コアコードにステップインできるようになります。

注:

ユーザーは、常にこのコードを PnP に追加された最新の変更内容に更新する必要があります。

手順 2: タイマージョブクラスを作成し、タイマージョブロジックを追加する

SimpleJob という名前のタイマージョブのクラスを追加します。
このクラスに TimerJob 抽象基本クラスを継承させます。
コンストラクターで、タイマージョブに名前 (base("SimpleJob")) を付け、TimerJobRun イベントハンドラーを接続します。
タイマージョブロジックを TimerJobRun イベントハンドラーに追加します。

結果は、次のようになります。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.SharePoint.Client;
using OfficeDevPnP.Core.Framework.TimerJobs;

namespace Core.TimerJobs.Samples.SimpleJob
{
    public class SimpleJob: TimerJob
    {
        public SimpleJob() : base("SimpleJob")
        {
            TimerJobRun += 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);
        }
    }
}

手順 3: タイマージョブを使用するように Program.cs を更新する

前の手順で作成したタイマージョブは、実行する必要があります。これを行うには、次の手順で Program.cs を更新します。

タイマージョブクラスをインスタンス化します。
タイマージョブの認証の詳細を提供します。次の例では、SharePoint Online に対する認証にユーザー名とパスワードを使用します。
タイマージョブプログラムがアクセスする 1 つ以上のサイトを追加します。この例では、URL にワイルドカード文字を使用します。タイマージョブは、このワイルドカード URL と一致するすべてのサイトで動作します。
Run メソッドを呼び出すことにより、タイマージョブを開始します。

static void Main(string[] args)
{
    // Instantiate the timer job class
    SimpleJob simpleJob = new SimpleJob();

    // The provided credentials need access to the site collections you want to use
    simpleJob.UseOffice365Authentication("user@tenant.onmicrosoft.com", "pwd");

    // Add one or more sites to operate on
    simpleJob.AddSite("https://<tenant>.sharepoint.com/sites/d*");

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

タイマージョブの展開オプション

前の手順は、単純なタイマージョブを示しています。次の手順では、タイマージョブを展開します。

タイマージョブは、ホスティングプラットフォーム上でスケジュールを設定する必要がある .exe ファイルです。選択されたホスティングプラットフォームによって、展開が異なります。次のセクションでは、2 つの最も一般的なホスティングプラットフォームオプションについて説明します。

ホスティングプラットフォームとして Azure を使用する。
ホスティングプラットフォームとして Windows Server を使用する。

Azure WebJobs を使用して Azure にタイマージョブを展開する

タイマージョブを展開する前に、ユーザーの介入なしにジョブを実行できることを確認します。この記事のサンプルでは、ユーザーにパスワードまたはクライアントシークレットの入力を求めるメッセージが表示されます (詳細は「認証」を参照してください)。これはテスト時は機能しますが、展開時は機能しません。すべての既存のサンプルでは、ユーザーに対して、app.config ファイルを使用したパスワードまたはクライアントシークレットの入力を許可します。

  <appSettings>
    <add key="user" value="user@tenant.onmicrosoft.com"/>
    <add key="password" value="your password goes here!"/>
    <add key="domain" value="Contoso"/>
    <add key="clientid" value="a4cdf20c-3385-4664-8302-5eab57ee6f14"/>
    <add key="clientsecret" value="your clientsecret goes here!"/>
  </appSettings>

app.config ファイルにこれらの変更を追加したら、Visual Studio からタイマージョブを実行し、ユーザーの介入なしで動作することを確認します。

Azure への実際の展開は、Azure WebJobs に基づきます。このタイマージョブの例を展開するには、次の手順を実行します。

Visual Studio でプロジェクトを右クリックし、[Azure WebJob として発行] を選択します。
タイマージョブのスケジュールを指定してから、[OK] を選択します
発行先として [Microsoft Azure Websites] を選択します。 Azure にサインインして、タイマージョブをホストする Azure Web サイトを選択するように求められます (必要に応じて新しく作成することもできます)。
[発行] を選択し、WebJob を Azure にプッシュします。
タイマージョブが発行されたら、Visual Studio または Azure portal からジョブをトリガーしてその実行を確認できます。
また、新しい Azure portal からジョブを選択して、[実行] を選択することにより、タイマージョブを実行することもできます。新しいポータルから WebJobs と連動する方法の詳細については、「Azure App Service で WebJobs を使用してバックグラウンドタスクを実行する」の記事を参照してください。

注:

Azure WebJob の展開に関する詳細なガイダンスについては、「Office 365 サイト用の Azure WebJobs ("タイマージョブ") の使用の開始」を参照してください。

Windows スケジューラを使用して Windows Server にタイマージョブを展開する

Windows Server に展開する場合、ユーザーの介入なしにタイマージョブを実行する必要があります。

前のセクション「Azure WebJobs を使用して Azure にタイマージョブを展開する」で説明したように app.config ファイルを変更します。
ジョブのリリースバージョンを、実行するサーバーにコピーします。

重要

サーバー上に追加のファイルまたはプログラムをインストールしなくてもジョブを実行できるよう、関連するアセンブリ、.exe ファイル、および .config ファイルのすべてをコピーします。
タイマージョブの実行をスケジュールします。組み込みの Windows タスクスケジューラを使用することをお勧めします。 Windows タスクスケジューラを使用するには、次の手順を実行します。
1. タスクスケジューラを開きます ([コントロールパネル]>[タスクスケジューラ])。
2. [タスクの作成] を選択し、タスクを実行する名前とアカウントを指定します。
3. [トリガー] を選択して、新しいトリガーを追加します。タイマージョブのスケジュールを指定します。
4. [アクション] を選択して、[プログラムの開始] アクションを選択し、タイマージョブの .exe ファイルを選択してから、フォルダーで開始を設定します。
5. [OK] を選択して、タスクを保存します。

Windows タスクスケジューラ

タイマージョブフレームワークの詳細

このセクションでは、タイマージョブフレームワークの機能と動作について詳しく説明します。

構造

TimerJob クラスは、次のパブリックプロパティ、メソッド、およびイベントが含まれている抽象基本クラスです。

TimerJob クラスの構造

ほとんどのプロパティとメソッドについては、以降のセクションで詳しく説明します。ここでは、それ以外のプロパティとメソッドについて説明します。

IsRunning プロパティ: タイマージョブが実行中かどうかを示す値を取得します。実行中の場合は true の値に、実行中でない場合は false の値になります。
Name プロパティ: タイマージョブの名前を取得します。名前は、タイマージョブのコンストラクターで最初に設定されます。
SharePointVersionプロパティ: SharePoint のバージョンを取得または設定します。このプロパティは、読み込まれている Microsoft.SharePoint.Client.dll のバージョンに基づいて自動的に設定されます。通常は変更しないでください。ただし、v16 CSOM ライブラリを v15 (オンプレミス) 展開で使用する場合はこのプロパティを変更できます。
Version プロパティ: このタイマージョブのバージョンを取得します。バージョンは最初、タイマージョブのコンストラクターで設定されるか、コンストラクターで設定されない場合は既定値の 1.0 に設定されます。

タイマージョブの実行を準備するには、最初にそれを構成する必要があります。

認証設定を提供します。
範囲 (サイトのリスト) を提供します。
オプションとして、タイマージョブのプロパティを設定します。

タイマージョブの実行が開始されると、実行の観点から次の全体的な手順が実行されます。

サイトを解決する: ワイルドカードのサイト URL (https://tenant.sharepoint.com/sites/d* など) が既存のサイトの実際のリストに解決されます。サブサイトの展開が要求された場合は、解決済みのサイトリストがすべてのサブサイトを使用して展開されます。
現在のスレッド設定に基づいて作業バッチを作成し、バッチごとに 1 つのスレッドを作成します。
スレッドが作業バッチを実行し、リスト内の各サイトに対して TimerJobRun イベントを呼び出します。

各手順の詳細については、次のセクションをご覧ください。

認証

タイマージョブを使用する前に、タイマージョブに SharePoint への認証方法を指示する必要があります。フレームワークが現在サポートしているのは、AuthenticationType 列挙型、Office365、NetworkCredentials、および AppOnly を使用したアプローチです。また、次のメソッドを使用した場合も、AuthenticationType プロパティが Office365、NetworkCredentials、および AppOnly に適切な値に自動的に設定されます。

次のフローチャートでは、実行する手順の後ろに、それぞれのアプローチの詳細な説明が続きます。

認証手順のフローチャート

ユーザー資格情報

Office 365 に対して実行するためのユーザー資格情報を指定するには、次の 2 つのメソッドを使用できます。

public void UseOffice365Authentication(string userUPN, string password)
public void UseOffice365Authentication(string credentialName)

最初のメソッドは、ユーザー名とパスワードを受け取ります。 2 番目のメソッドでは、Windows 資格情報マネージャーに保存されている汎用の資格情報を指定できます。次のスクリーンショットは、bertonline 汎用資格情報を示しています。これを使用してタイマージョブを認証するために、2 つ目のメソッドのパラメーターとして bertonline を指定します。

Windows 資格情報マネージャー

SharePoint オンプレミスに対して実行するための同様のメソッドがあります。

public void UseNetworkCredentialsAuthentication(string samAccountName, string password, string domain)
public void UseNetworkCredentialsAuthentication(string credentialName)

アプリ専用

アプリ専用の認証は、テナントスコープアクセス許可を付与できるため、優先メソッドです。ユーザー資格情報の場合は、ユーザーアカウントに必要なアクセス許可が付与されている必要があります。

注:

特定のサイト解決ロジックがアプリ専用の認証で動作しない場合があります。詳細は、次のセクションで説明します。

アプリ専用の認証用にジョブを構成するには、次のいずれかのメソッドを使用します。

public void UseAppOnlyAuthentication(string clientId, string clientSecret)
public void UseAzureADAppOnlyAuthentication(string clientId, string clientSecret)

Office 365 または SharePoint オンプレミスのいずれかで同じメソッドを使用し、アプリ専用の認証を使用したタイマージョブを環境間で容易に移動することができます。

注:

アプリ専用の認証を使用する場合は、AuthenticationType.AppOnly で動作しない API が使用されていると、タイマージョブロジックが失敗します。一般的な例として、検索 API、分類ストアへの書き込み、およびユーザープロファイル API の使用があります。

実行するサイト

タイマージョブを実行する場合は、それを実行する 1 つ以上のサイトが必要です。

タイマージョブにサイトを追加する

タイマージョブにサイトを追加するには、次のメソッドのセットを使用します。

public void AddSite(string site)
public void ClearAddedSites()

サイトを追加するには、完全修飾 URL (https://tenant.sharepoint.com/sites/dev など) とワイルドカード URL のどちらかを指定します。

ワイルドカード URL は、アスタリスク (*) で終わる URL です。 * は 1 つしか使用できず、URL の最後の文字にする必要があります。ワイルドカード URL のサンプルが https://tenant.sharepoint.com/sites/* です。この URL は、そのサイトの管理対象パスの下のすべてのサイトコレクションを返します。別の例として、https://tenant.sharepoint.com/sites/dev* は、URL に dev が含まれるすべてのサイトコレクションを返します。

通常、サイトは、タイマージョブオブジェクトをインスタンス化するプログラムによって追加されますが、必要に応じて、タイマージョブで渡されたサイトのリストを制御することもできます。次のサンプルに示すように、UpdateAddedSites 仮想メソッドのメソッド上書きを追加してこれを実行します。

public override List<string> UpdateAddedSites(List<string> addedSites)
{
    // Let's assume we're not happy with the provided list of sites, so first clear it
    addedSites.Clear();

    // Manually adding a new wildcard Url, without an added URL the timer job will do...nothing
    addedSites.Add("https://bertonline.sharepoint.com/sites/d*");

    // Return the updated list of sites
    return addedSites;
}

列挙型の資格情報を指定する

ワイルドカード URL を追加して認証をアプリ専用に設定したら、列挙型の資格情報を指定します。列挙型の資格情報は、実際のサイトのリストを返すサイト照合アルゴリズムで使用されるサイトコレクションのリストを取得するために使用されます。

サイトコレクションのリストを取得するためのタイマーフレームワークの動作は Office 365 (v16) とオンプレミス (v15) で異なります。

Office 365: Tenant.GetSiteProperties メソッドが「標準」のサイトコレクションの読み取りに使用され、検索 API が OneDrive for Business サイトコレクションの読み取りに使用されます。
SharePoint オンプレミス:すべてのサイトコレクションを読み取るために検索 API が使用されます。

検索 API がユーザーコンテキストと連動しない場合は、タイマージョブが指定された列挙型の資格情報にフォールバックします。

Office 365 に対して実行するためのユーザー資格情報を指定するには、次の 2 つのメソッドを使用できます。

public void SetEnumerationCredentials(string userUPN, string password)
public void SetEnumerationCredentials(string credentialName)

SharePoint オンプレミスに対して実行するための同様のメソッドがあります。

public void SetEnumerationCredentials(string samAccountName, string password, string domain)
public void SetEnumerationCredentials(string credentialName)

最初のメソッドは、ユーザー名、パスワード、およびオプションでドメイン (オンプレミスの場合) を受け取るだけです。 2 つ目のメソッドは、Windows 資格情報マネージャーに保存されている汎用の資格情報を指定します。資格情報マネージャーの詳細については、「認証」を参照してください。

サブサイトの展開

多くの場合、タイマージョブコードは、サイトコレクションのルートサイトおよびそのサイトコレクションのすべてのサブサイトに対して実行されます。これを行うには、ExpandSubSites プロパティを true に設定します。これにより、サイト解決手順の一部として、タイマージョブがサブサイトに展開されます。

解決されたサイトおよび展開されたサイトを上書きする

タイマーフレームワークでワイルドカードサイトが解決され、オプションでサブサイトが展開されたら、次の手順はサイトのリストの処理です。サイトのリストを処理する前に、サイトのリストの変更が必要となる場合があります。たとえば、特定のサイトを削除したり、リストにサイトを追加したりする場合があります。この手順は、ResolveAddedSites 仮想メソッドを上書きすることで実現できます。次のサンプルは、ResolveAddedSites メソッドを上書きして、リストから 1 つのサイトを削除する方法を示しています。

public override List<string> ResolveAddedSites(List<string> addedSites)
{
    // Use default TimerJob base class site resolving
    addedSites = base.ResolveAddedSites(addedSites);

    //Delete the first one from the list...simple change. A real life case could be reading the site scope
    //from a SQL (Azure) DB to prevent the whole site resolving.
    addedSites.RemoveAt(0);

    //Return the updated list of resolved sites...this list will be processed by the timer job
    return addedSites;
}

TimerJobRun イベント

タイマージョブフレームワークでは、サイトのリストが作業バッチに分割されます。サイトの各バッチは、独自のスレッドで実行されます。既定で、フレームワークによって、5 つのバッチと、それらを実行する 5 つのスレッドが作成されます。タイマージョブスレッドオプションの詳細については、「スレッド」を参照してください。

スレッドがバッチを処理すると、TimerJobRun イベントがタイマーフレームワークによってトリガーされ、タイマージョブを実行するために必要なすべての情報が提供されます。タイマージョブはイベントとして実行されるため、コードでイベントハンドラーを TimerJobRun イベントに接続する必要があります。

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

void SimpleJob_TimerJobRun(object sender, TimerJobRunEventArgs e)
{
    // your timer job logic goes here
}

もう 1 つの方法では、次のようにインライン委任を使用します。

public SimpleJob() : base("SimpleJob")
{
    // Inline delegate
    TimerJobRun += delegate(object sender, TimerJobRunEventArgs e)
    {
        // your timer job logic goes here
    };
}

TimerJobRun イベントが発生すると、タイマージョブロジックを記述するために必要な情報を提供する TimerJobRunEventArgs オブジェクトが送られてきます。このクラスでは、次の属性とメソッドを使用できます。

TimerJobRunEventArgs クラスの構造

いくつかのプロパティとすべてのメソッドが、次のセクションで説明するオプションの状態管理機能で使用されます。ただし、次のプロパティは、使用されている構成に関係なく、すべてのイベントで常に使用できます。

Url プロパティ: 動作対象のタイマージョブのサイトの URL を取得または設定します。サイトコレクションのルートサイトにすることができますが、サイトの展開が行われた場合は、サブサイトにすることもできます。
ConfigurationData プロパティ: 追加のタイマージョブ構成データを取得または設定します (オプション)。この構成データは、TimerJobRunEventArgs オブジェクトの一部として渡されます。
WebClientContext プロパティ: 現在の URL の ClientContext オブジェクトを取得または設定します。このプロパティは、Url プロパティで定義されたサイトの ClientContext オブジェクトです。これは、通常、タイマージョブコードで使用される ClientContext オブジェクトです。
SiteClientContext プロパティ: サイトコレクションのルートサイトの ClientContext オブジェクトを取得または設定します。このプロパティは、タイマージョブがアクセスするために必要なルートサイトへのアクセス権を提供します。たとえば、タイマージョブは、SiteClientContext プロパティを使用してページレイアウトをマスターページギャラリーに追加できます。
TenantClientContext プロパティ: テナント API と連動する ClientContext オブジェクトを取得または設定します。このプロパティは、テナント管理サイトの URL を使用して構築された ClientContext オブジェクトを提供します。タイマージョブの TimerJobRun イベントハンドラーでテナント API を使用するには、この TenantClientContext プロパティを使用して新しい Tenant オブジェクトを作成します。

すべての ClientContext オブジェクトが、「認証」に記載されている認証情報を使用します。ユーザー資格情報を選択した場合は、ユーザーアカウントが、指定されたサイトに対して動作するために必要なアクセス許可を持っていることを確認します。アプリ専用を使用している場合は、テナントスコープアクセス許可をアプリ専用プリンシパルに設定することをお勧めします。

状態管理

タイマージョブロジックを作成する場合は、状態を持続させる必要があります。たとえば、サイトが最後に処理された時点を記録するためやタイマージョブのビジネスロジックをサポートするデータを保存するためなどです。このために、タイマージョブフレームワークは状態管理機能を備えています。

状態管理では、標準およびカスタムのプロパティセットを、処理されたサイトの Web プロパティバッグの JSON シリアル化された文字列 (名前 = タイマージョブの名前 + 「_Properties」) として保存および取得します。 TimerJobRunEventArgs オブジェクトの既定のプロパティを以下に示します。

PreviousRun プロパティ: 前回の実行の日付と時刻を取得または設定します。
PreviousRunSuccessful プロパティ: 前回の実行が正常に完了したかどうかを示す値を取得または設定します。タイマージョブの作成者は、タイマージョブの実装の一部として CurrentRunSuccessful プロパティを設定することにより、ジョブの実行に成功というフラグを付ける必要があることに注意してください。
PreviousRunVersion プロパティ: 前回の実行のタイマージョブバージョンを取得または設定します。

これらの標準プロパティの横には、TimerJobRunEventArgs オブジェクトの Properties コレクションにキーワード (keyword)値ペアを追加することで、独自のプロパティを指定するオプションもあります。これを容易にするために、次の 3 つのメソッドがあります。

SetProperty はプロパティを追加または更新します。
GetProperty はプロパティの値を返します。
DeleteProperty は、プロパティコレクションからプロパティを削除します。

次のコードは、状態管理の使用方法を示しています。

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

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

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

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

        if (!e.GetProperty("ScriptFileVersion").Equals("1.0", StringComparison.InvariantCultureIgnoreCase))
        {
            if (list == null)
            {
                // grab reference to 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)
        {
            // Oops, we need at least 2 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
        {
            // We're all good...let's remove the notification
            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)
    {
        e.CurrentRunSuccessful = false;
        e.SetProperty("LastError", ex.Message);
    }
}

状態は、1 つの JSON シリアル化プロパティとして保存されます。これは、他のカスタマイズにも使用できることを意味します。たとえば、タイマージョブが状態エントリ「SiteCompliant = false」を書き込んだ場合は、タイマージョブが、サイトが準拠していないと判断したことになるため、JavaScript ルーチンでユーザーのアクションを求めることができます。

スレッド

タイマージョブフレームワークは、既定で、スレッドを使用して作業を並列化します。スレッドは、サブサイトの展開 (要求された場合) と、各サイトに対する実際のタイマージョブロジックの実行 (TimerJobRun イベント) の両方に使用されます。スレッドの実装を制御するには、次のプロパティを使用できます。

UseThreading プロパティ: スレッドを使用するかどうかを示す値を取得または設定します。既定は true です。メインアプリケーションスレッドを使用してすべてのアクションを実行するには、false に設定します。
MaximumThreads プロパティ: このタイマージョブに使用するスレッドの数を取得または設定します。有効な値は 2 から 100 です。既定は 5 です。必ずしも多数のスレッドを使用する方が少数のスレッドを使用するより高速になるとは限りません。最適な数は、さまざまなスレッド数を使用したテストを通して特定する必要があります。既定の 5 スレッドは、ほとんどのシナリオでパフォーマンスを大幅に向上することがわかっています。

調整

タイマージョブはスレッドを使用し、大抵のタイマージョブの操作がリソース消費型であるため、タイマージョブの実行を調整することができます。調整を正しく処理するために、タイマージョブフレームワークと PnP コアの全体で、既定の ExecuteQuery メソッドではなく、ExecuteQueryRetry メソッドが使用されます。

注:

タイマージョブの実装コードで ExecuteQueryRetry を使用することが重要です。

同時実行の問題 - 同じスレッド内のサイトコレクションのすべてのサブサイトを処理する

複数のスレッドを使用してサブサイトを処理すると、タイマージョブで同時実行の問題が発生する可能性があります。

一例を挙げます。スレッド A はサイトコレクション 1 の最初のサブサイトのセットを処理し、スレッド B はサイトコレクション 1 の残りのサブサイトを処理します。タイマージョブがサブサイトとルートサイトを処理する (SiteClientContext オブジェクトを使用して) 場合は、スレッド A とスレッド B の両方がルートサイトを処理するため、同時実行の問題が発生する可能性があります。

同時実行の問題を回避する (1 つのスレッド内でタイマージョブを実行せずに) には、タイマージョブ内で GetAllSubSites メソッドを使用します。

次のコードは、タイマージョブ内で GetAllSubSites メソッドを使用する方法を示しています。

public class SiteCollectionScopedJob: TimerJob
{
    public SiteCollectionScopedJob() : base("SiteCollectionScopedJob")
    {
        // ExpandSites *must* be false as we'll deal with that at TimerJobEvent level
        ExpandSubSites = false;
        TimerJobRun += SiteCollectionScopedJob_TimerJobRun;
    }

    void SiteCollectionScopedJob_TimerJobRun(object sender, TimerJobRunEventArgs e)
    {
        // Get all the subsites in the site we're processing
        IEnumerable<string> expandedSites = GetAllSubSites(e.SiteClientContext.Site);

        // Manually iterate over the content
        foreach (string site in expandedSites)
        {
            // Clone the existing ClientContext for the sub web
            using (ClientContext ccWeb = e.SiteClientContext.Clone(site))
            {
                // Here's the timer job logic, but now a single site collection is handled in a single thread which
                // allows for further optimization or prevents race conditions
                ccWeb.Load(ccWeb.Web, s => s.Title);
                ccWeb.ExecuteQueryRetry();
                Console.WriteLine("Here: {0} - {1}", site, ccWeb.Web.Title);
            }
        }
    }
}

ログ

タイマージョブフレームワークは、PnP コアライブラリの一部であるため、PnP コアログコンポーネントを使用します。組み込みの PnP コアログをアクティブにするには、該当する構成ファイル (app.config または web.config) を使用して構成します。次の例は、必要な構文を示しています。

  <system.diagnostics>
    <trace autoflush="true" indentsize="4">
      <listeners>
        <add name="DebugListenter" type="System.Diagnostics.TextWriterTraceListener" initializeData="trace.log" />
        <!--<add name="consoleListener" type="System.Diagnostics.ConsoleTraceListener" />-->
      </listeners>
    </trace>
  </system.diagnostics>

上の構成ファイルを使用すると、タイマージョブフレームワークは System.Diagnostics.TextWriterTraceListener を使用して、タイマージョブの .exe と同じフォルダー内の trace.log ファイルにログを書き込みます。利用可能なその他のトレースリスナーには、次のようなものがあります。

ConsoleTraceListener はログをコンソールに出力します。
「クラウド診断 - Windows Azure でのログ収集とトレースを制御する」に記載されているメソッド。このメソッドは、Microsoft.WindowsAzure.Diagnostics.DiagnosticMonitorTraceListener を使用します。その他の Azure の技術資料は、こちらにあります。
- Azure App Service で Web アプリケーションの診断ログを有効にする
- Visual Studio を使用して Azure App Service 内の Web アプリケーションをトラブルシューティングする

タイマージョブフレームワークと同じログアプローチを、カスタムのタイマージョブコードに使用することを強くお勧めします。タイマージョブコード内で、PnP コア Log クラスを使用できます。

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

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

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

        // Additional timer job logic...

        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);
    }
}

次の方法で共有

PnP タイマージョブフレームワーク

タイマージョブの単純な例

手順 1: コンソールプロジェクトを作成し、PnP コアを参照する

手順 2: タイマージョブクラスを作成し、タイマージョブロジックを追加する

手順 3: タイマージョブを使用するように Program.cs を更新する

タイマージョブの展開オプション

Azure WebJobs を使用して Azure にタイマージョブを展開する

Windows スケジューラを使用して Windows Server にタイマージョブを展開する

タイマージョブフレームワークの詳細

構造

認証

ユーザー資格情報

アプリ専用

実行するサイト

タイマージョブにサイトを追加する

列挙型の資格情報を指定する

サブサイトの展開

解決されたサイトおよび展開されたサイトを上書きする

TimerJobRun イベント

状態管理

スレッド

調整

同時実行の問題 - 同じスレッド内のサイトコレクションのすべてのサブサイトを処理する

ログ

関連項目

その他のリソース

次の方法で共有

PnP タイマー ジョブ フレームワーク

タイマー ジョブの単純な例

手順 1: コンソール プロジェクトを作成し、PnP コアを参照する

手順 2: タイマー ジョブ クラスを作成し、タイマー ジョブ ロジックを追加する

手順 3: タイマー ジョブを使用するように Program.cs を更新する

タイマー ジョブの展開オプション

Azure WebJobs を使用して Azure にタイマー ジョブを展開する

Windows スケジューラを使用して Windows Server にタイマー ジョブを展開する

タイマー ジョブ フレームワークの詳細

構造

認証

ユーザー資格情報

アプリ専用

実行するサイト

タイマー ジョブにサイトを追加する

列挙型の資格情報を指定する

サブサイトの展開

解決されたサイトおよび展開されたサイトを上書きする

TimerJobRun イベント

状態管理

スレッド

調整

同時実行の問題 - 同じスレッド内のサイト コレクションのすべてのサブサイトを処理する

ログ

関連項目

その他のリソース

PnP タイマージョブフレームワーク

タイマージョブの単純な例

手順 1: コンソールプロジェクトを作成し、PnP コアを参照する

手順 2: タイマージョブクラスを作成し、タイマージョブロジックを追加する

手順 3: タイマージョブを使用するように Program.cs を更新する

タイマージョブの展開オプション

Azure WebJobs を使用して Azure にタイマージョブを展開する

Windows スケジューラを使用して Windows Server にタイマージョブを展開する

タイマージョブフレームワークの詳細

タイマージョブにサイトを追加する

同時実行の問題 - 同じスレッド内のサイトコレクションのすべてのサブサイトを処理する