SharePoint Foundation コマンドレットの開発ガイドライン
最終更新日: 2010年3月24日
適用対象: SharePoint Foundation 2010
SharePoint 用の独自の Windows PowerShell コマンドレット (SPCmdlet 基本クラスから派生したカスタム コマンドレット) を作成する場合は、必ず SharePoint 固有の設計ガイドラインを使用して、作成するコマンドレットが、SharePoint 管理シェルで公開される SharePoint コマンドレット ライブラリのコマンドレットと完全に互換性を持つようにしてください。さらに、SharePoint Foundation では、SharePoint 展開との完全な相互運用性を保証する設計パターンも推奨しています。
SharePoint コマンドレットを作成するための方法
SharePoint 固有のコマンドレットを設計するときは、常に次の作業を行います。
コマンドレットの名詞を定義する。
コマンドレット名詞のプロパティを定義する。
コマンドレットの動詞とパラメーターを定義する。
コマンドレットのエラー、進行状況、およびパイプラインを定義する。
このプロセスを実行すると、開発するコンポーネントと機能のコマンドレット セットの包括的な定義ができあがります。
コマンドレットの名詞を定義する
コマンドレット名詞を定義するときは、その機能で何を管理するのかを明確にしておく必要があります。名詞はシステム管理者が管理する項目だと考えてください。これらは、SharePoint オブジェクト (SPSite オブジェクト、SPWeb オブジェクトなど) であることもあれば、テンプレートからインストールされた機能 (SPFeature オブジェクトなど) であることもあれば、Web パーツであることもあります。
原則として、名詞の数を少なくして、各名詞のプロパティを多くするよりも、名詞の数を多くして、各名詞のプロパティを少なくする方が望ましいといえます。1 つの名詞のプロパティが 15 個を超えると多すぎます。
システム管理者に公開する非持続的な実行時状態情報を特定します。また、持続的でない可能性があってもシステム管理者に返す必要のある状態情報 (たとえば、サービスの実行状態) も特定します。
新たに定義した名詞を 2 つ以上の異なる名詞に分割するかどうかを検討します。意味的に異なる項目ごとに別個の名詞を作成してください。機能またはコンポーネントの仕様を使用して、1 つの名詞が複数の概念や機能に及んでいないか確認してください。
1 つの名詞が複数のデータ ソース (物理または論理) に及んでいる場合は、その名詞をデータ ソース境界で分割します。単一のデータベース オブジェクトまたは SharePoint オブジェクトのみで持続する、論理的に独立したプロパティ サブセットを特定してください。多くの場合、このサブセットは別個の名詞にする必要があります。ただし、結果として作られる名詞が論理的に独立していて、それらがシステム管理者から見て別個のエンティティであることが明白である (容易に区別できる) ことが条件です。
複数の名詞で使用される持続的データ ソース オブジェクトがある場合は、それらの名詞をデータ ソース オブジェクトごとに 1 つの名詞にまとめます。また、有効期間の違いが主な相違点である名詞も 1 つにまとめてください。そのような名詞の作成と削除は別々に管理できるからです。
コマンドレット名詞のプロパティを定義する
Identity プロパティを定義します。GUID など、一意で不変の値を持つ Identity プロパティがすべての名詞に必要です。
名詞の pipebind を作成します。pipebind はオブジェクトを一意に識別できるすべてのプロパティを結合する必要があります。
名詞のすべてのパブリック プロパティを定義します。名詞の定義はパブリック API の場合と同様に行います。名詞のインスタンスが返されるとき、関連するすべてのパブリック プロパティがコマンド ラインに表示されます。
プロパティごとにデータ型を定義します。形式検証コードを名詞ではなくてプロパティの型に付けることができるように、プロパティの型指定は厳密にする必要があります。たとえば、電子メール アドレスを表すプロパティは、文字列型ではなく EmailAddress 型にします。
異常に大きいプロパティを調べます。異常に大きい (10 KB を超える) プロパティは、2 つ以上のプロパティに分割してください。
多数の要素を持つプロパティ コレクション (たとえば、要素の数が 100 を超えるコレクション) を調べます。そのような大きいプロパティ コレクションを削除し、それらの要素を別々の名詞に分割してください。その後、それらの新しい名詞に対して New、Remove、Get、Set の各動詞を定義します。
たとえば、SPWeb オブジェクトに Users というプロパティがあり、大量の要素が含まれる可能性があるとします。問題を避けるには、リスト中の 1 つの要素を表す SPUser という名詞を作成し、対応する New、Remove、Get、Set の各動詞を追加します。
コマンドレットの動詞とパラメーターを定義する
目的の名詞にどの基本動詞 (Get、Set、New、Remove) を適用するかを決定します。少なくとも、システム管理者が設定の取得および変更 (Set) を行えることが必要です。さらに、管理者が新しいインスタンスの作成 (New) および既存のインスタンスの削除 (Remove) を行うことも必要になることがあります。
Get コマンドレットの動作を定義します。
Get 動詞では、パラメーターが指定されない場合に、すべてのインスタンスを取得する必要があります。また、Windows PowerShell パイプラインにインスタンスを書き込むことで、それを行う必要があります。ただし、非常に大きな結果セットを返す可能性のある操作には、既定の制限を指定する Limit パラメーターを含める必要があります。もちろん、この方法で結果セットを制限するときは、制限された結果セットから一部の結果が除外されている可能性があることをユーザーに通知する必要があります。
Get 動詞には、Identity パラメーターが必要です。これが指定された場合、対応するコマンドレットは、その ID に関連付けれたインスタンスのみを返します。指定された ID が一意でない場合、コマンドレットは指定された ID 値を持つインスタンスをすべて返します。
Get 動詞には、オプションのフィルター パラメーターを付け加えることができます。たとえば、コマンドレット Get-SPSite に ContentDatabase パラメーターを定義し、結果セットを、指定されたコンテンツ データベースにあるサイト コレクションに限定できるようにする方法があります。また、コマンドレットがローカルな (コンピューター固有の) 構成情報を返す場合は、Get 動詞に Server パラメーターが必要です。
Set コマンドレットの動作を定義します。
Set 動詞には、変更対象のインスタンスを識別するための Identity パラメーターが必要です。このパラメーターでは ID (たとえば、GUID) または名前を受け取ることができるようにします。名前が指定され、その名前が複数のインスタンスと一致する場合、コマンドレットはエラーを返す必要があります。
Set コマンドレットの Identity パラメーターはパイプライン入力を受け付ける必要があります。
Set 動詞は、対応する Get コマンドレットで取得される名詞の書き込み可能なプロパティを (設定すると悪影響が生じるものを除いて) すべて公開する必要があります。
Set 動詞には、この名詞型のインスタンス全体を表すオプションの Instance パラメーターが必要です。Instance パラメーターはパイプライン入力を (値によって) 受け取る必要があります。
New コマンドレットの動作を定義します。
New 動詞では、名詞の書き込み可能なプロパティのサブセットをパラメーターとして受け取る必要があります。それ以外のパラメーターは既定値に設定します。また、New コマンドレットは、新たに作成されたインスタンス オブジェクトをパイプラインに返すことによって、パイプライン内のそれ以降のコマンドレットが新しいインスタンスを使用できるようにする必要があります。
Remove コマンドレットの動作を定義します。
Remove コマンドレットには、ID または名前を受け取る Identity パラメーターが必要です。名前が指定され、その名前が複数のインスタンスと一致する場合、コマンドレットはエラーを返す必要があります。
Identity パラメーターはパイプライン入力を受け付ける必要があります。また、削除などの破壊操作はすべて、Confirm パラメーターと WhaIf パラメーターをサポートする必要があります。Windows PowerShell と SharePoint Foundation 2010 の基本クラスにはこれらのパラメーターをサポートする手段が用意されているので、これは容易に実装できます。
名詞に対応する他の動詞を特定して定義します。
たとえば、SPContentDatabase 名詞では、指定されたデータベースのマウントをサポートするために、Mount 動詞が必要になることがあります。適切な動詞の選択をサポートするために、十分にテストされた管理シナリオとユース ケースを使用してください。
この場合も、追加するすべてのコマンドレットに、パイプライン入力を受け付ける Identity パラメーターが必要です。Identity パラメーターではオブジェクトの ID (PipeBind) を受け付けます。また、削除などの破壊操作はすべて、Confirm パラメーターと WhaIf パラメーターをサポートする必要があります。
有害な副作用が生じる可能性のあるプロパティを特定します。
有害な副作用が生じる可能性のあるプロパティについては、悪影響を軽減するために追加的な操作が必要になることもあります。そうした軽減のためのコマンドレットには、パイプライン入力を受け付ける Identity パラメーターが必要です。
定義するコマンドレットごとに次の作業を行います。
(a) コマンドレットの必要条件のリストを作成します。たとえば、コマンドレットをある特定のシステム状態でのみ実行できる場合、そのコマンドレットでは、実行前にすべての状態必要条件が満たされていることを検証する必要があります。
(b) 操作のリストを作成します。コマンドレットが実行できる操作の完全なリストを指定してください。コマンドレットは、これらの操作を実行してから検証する必要があります。この操作リストはコマンドレットの機能明細となります。
コマンドレットのエラー、進行状況、およびパイプラインを定義する
すべてのエラー状態とエラー状態動作を特定します。つまり、コマンドレットがエラーとなる可能性のある状態を網羅したリストを作成します。次に、状態ごとに期待される動作を記述します。コマンドレットは基本的なエラー管理を備えている必要があります。
コマンドレットは、エラー発生時に部分的な変更をクリーンアップし、エラーを説明する (また、必要に応じてローカライズされた) エラー メッセージを返す必要があります。また、コマンドレットは、エラー状態からの回復方法を判定して、システム管理者にその情報を開示する必要があります。
終了するエラーと終了しないエラーを区別します。
長時間にわたって実行される操作を特定します。コマンドレットの実行に平均で 20 秒以上かかると予想される場合、コマンドレットは操作を完了するために、進行状況情報を提供することで、中断された操作があるように見えるのを避ける必要があります。
コマンドレットがリターン オブジェクトをパイプラインに直接書き込むようにしてください。取得したオブジェクトを内部の配列にバッファーすることは避けます。パイプラインに書き込むと、ダウンストリームのコマンドレットがパイプライン内の先行するオブジェクトに対して遅滞なく作用することができます。
類似したパラメーターをグループ化します。コマンドレットのパラメーターの数を 16 個以内にしてください (ただし、これは Identity と Name を除いた数です)。オブジェクト メソッドがめったに呼び出されない場合や、オブジェクト モデル メソッドが存在する場合は、コマンドレットのパラメーターは必要ありません。多数のパラメーターをグループ化できる場合は、グループ オブジェクトを受け付ける 1 つのパラメーターを記述してください。