SharePoint 管理シェル用コマンドレットの作成に関する重要な概念
最終更新日: 2009年10月1日
適用対象: SharePoint Foundation 2010
この記事の内容
コマンドレットのパラメーター
パイプラインとパイプ処理
PipeBind オブジェクト
SharePoint 用の Windows PowerShell コマンドレットを作成するときに役立つ重要な概念がいくつかあります。以下では、SharePoint 用の Windows PowerShell コマンドレットの実装を支援する重要な概念をいくつか説明します。
コマンドレットのパラメーター
ユーザーはパラメーターを文字列として入力しますが、Windows PowerShell はパラメーター定義に基づいて、それらの文字列値を内部的に適切な型に変換しようとします。したがって、作成するコマンドレットで、渡されたパラメーター値が有効なデータ型かどうかを検証しなければなりません。
文字列型または整数型のパラメーターを渡すのは、その型のすべての値がパラメーターとして有効である場合を除いて避けてください。代わりに、パラメーターの範囲と形式を絞り込んだクラスを定義してください。また、パラメーター型の Parse(String) メソッドを使用してパラメーターを検証してください。Windows PowerShell は、文字列型を他のデータ型に変換するために Parse() メソッドの使用をサポートしています。
パイプラインとパイプ処理
Cmd.exe の機能を超える Windows PowerShell の強化機能の中で最も重要なものの 1 つが、Windows PowerShell では一連の単純なコマンドレットを結合して 1 つの "パイプライン" にまとめることができるというネイティブな機能です。パイプラインとは、一連のコマンドのことです。パイプラインでは、あるコマンドからの出力オブジェクトを入力オブジェクトとして後続のコマンドに渡す ("パイプする") ことができます。コマンド パイプラインを利用することで、コマンドレット開発者は出力オブジェクトを保存して再利用できる複雑で柔軟なコマンド パイプラインを作成できます。
パイプ処理のプロセスは、Windows PowerShell で制御されるオブジェクト パイプラインに出力オブジェクトが書き込まれるというコマンドレットの動作に依存しています。これにより、Windows PowerShell はパイプライン内のそのオブジェクトを次のコマンドレットのパラメーターと照合することができます。
パイプライン処理がうまく機能するためには、前のコマンドレットと後続のコマンドレットの入力との間に明示的な対応がなければなりません。この対応がオブジェクト レベルで存在する場合は、パイプライン内の前のオブジェクトが次のコマンドレットのパラメーターと一致します (これは "値によるパイプ処理" と呼ばれます)。また、この対応がプロパティ レベルで存在する場合は、パイプライン内の前のオブジェクトのプロパティが次のコマンドレットのパラメーターと一致します。
値によるパイプ処理
値によるパイプライン処理とは、ダウンストリームのコマンドレットがパイプライン内のあるオブジェクトを、そのオブジェクトが正しい型であれば、丸ごと使用することを意味します。値によるパイプ処理は一般に Set コマンドレットを使って行われます (オブジェクトト全体を渡すことでデータ ソースからの読み取り操作が省かれます) が、複製をサポートする New コマンドレットによっても行われます。値によるパイプライン処理は、ダウンストリームのコマンドレットがアップストリームのコマンドレットから出力されたオブジェクトを再読み取りできない場合にも使用されます。
PipeBind オブジェクト
PipeBind オブジェクトは、SharePoint 用の Windows PowerShell に固有の特別なオブジェクトであり、SharePoint Foundation 用に最適化された特殊なパラメーター セットという第 2 のレイヤーを提供します。
SharePoint Foundation 2010 のオブジェクトをコマンドレットのパラメーターとして使用するときは、SharePoint オブジェクトの代わりに適切な PipeBind オブジェクトを使用してください。これは非常に重要なことです。こうすると、コマンドレットのユーザーが適切な方法でパラメーターの値を指定できるからです。PipeBind オブジェクトは実のところ、パラメーターとしてのユーザー入力とパラメーター オブジェクト自体との間に存在するレイヤーを表しています。
たとえば、SPSite パラメーターを取るコマンドレットは、SPSite オブジェクト自体を取ることも、そのサイト コレクションの GUID 識別子を取ることも、そのサイト コレクションの URL を取ることもできます。Windows PowerShell ランタイムによってどんな表現が与えられようとも、実際の SPSite オブジェクトがコマンドレット自体に間違いなく与えられるようにするのは、SPSitePipeBind オブジェクトの役目です。
注意
PipeBind クラスは、特定のコマンドレットにバインドせずに、すべてのコマンドレットの間で共有されるようにしてください。PipeBind コマンドレットを作成するときは、コマンドレットの実装側に固有の要件が入り込まないようにしてください。
PipeBind オブジェクトの実装
PipeBind オブジェクトを実装するときは、SPCmdletPipeBind<TCmdletObject> 基本クラスから派生させる必要があります。このクラスを実装するには、次のことを行います。
クラス コンストラクターを実装します。
オブジェクトの Read() メソッドをオーバーライドします。
PipeBind クラスには少なくとも 1 つのコンストラクターが必要です。複数あってもかまいません。Windows PowerShell はパラメーターのバインドを試みるときに、指定されたパラメーターのパブリック コンストラクターのセットを反復処理し、パラメーター入力と PipeBind コンストラクターとの照合を試みます。つまり、パラメーターを表す入力の型として考えられる各型について、対応するコンストラクターが存在しなければならないということです。
SPCmdletPipeBind<TCmdletObject> オブジェクトの Read() メソッドは、SharePoint Foundation オブジェクト モデルで定義されているオブジェクト型を返します (public virtual TCmdletObject Read())。
オブジェクト モデル オブジェクトが正しく取得されるようにするには、PipeBind オブジェクトの実装ごとに Read() メソッドをオーバーライドする必要があります。必要に応じて、Read() メソッドの追加のオーバーライドを作成することにより、必要なパラメーターを提供することができます。
コマンドレットの ID と原子性
コマンドレットには、作用対象となるオブジェクトを指定する Identity パラメーターがなければなりません。コマンドレットを作成するときは、Identity パラメーターの値として一意の識別子を指定する必要があります。ただし、新しいコマンドレットは最初は識別子を持たず、オブジェクトのインスタンス化の後に初めて持つことができます。
コマンドレットの実行は原子性をシミュレートする必要があります。つまり、コマンドレットは、成功して、システムを変更された状態にするか、そうでなければ整然と失敗して、システムを実行前の状態に戻さなければなりません。要するに、コマンドレットは、失敗したときにシステムの状態を復元するためのメソッドを備えていなければなりません。