次の方法で共有

強くお勧めする開発ガイドライン

このセクションでは、コマンドレットを記述するときに従う必要があるガイドラインについて説明します。 コマンドレットを設計するためのガイドラインと、コマンドレット コードを記述するためのガイドラインに分かれています。 これらのガイドラインは、すべてのシナリオに適用できるわけではない場合があります。 ただし、それらが適用され、これらのガイドラインに従わない場合、ユーザーはコマンドレットを使用するときにエクスペリエンスが低下する可能性があります。

設計ガイドライン

コマンドレットと他のコマンドレットを使用する間の一貫性のあるユーザー エクスペリエンスを確保するために、コマンドレットを設計するときは、次のガイドラインに従う必要があります。 状況に適用される設計ガイドラインが見つかると、同様のガイドラインについては必ずコード ガイドラインを参照してください。

コマンドレット名に特定の名詞を使用する (SD01)

コマンドレットの名前付けに使用される名詞は、ユーザーがコマンドレットを検出できるように、非常に具体的である必要があります。 "server" などの汎用名詞には、製品名の短縮バージョンをプレフィックスとして付けます。 たとえば、名詞が Microsoft SQL Server のインスタンスを実行しているサーバーを参照する場合は、"SQLServer" などの名詞を使用します。 特定の名詞と承認された動詞の短いリストを組み合わせることで、コマンドレット名間の重複を回避しながら、ユーザーは機能をすばやく検出して予測できます。

ユーザー エクスペリエンスを強化するには、コマンドレット名に対して選択する名詞を単数形にする必要があります。 たとえば、Get-Processesの代わりに名前Get-Processを使用します。 コマンドレットが複数の項目に対して動作する可能性が高い場合でも、すべてのコマンドレット名に対してこの規則に従うことをお勧めします。

コマンドレット名にパスカル ケースを使用する (SD02)

パラメーター名にはパスカルケースを使用します。 つまり、動詞の最初の文字と名詞で使用されるすべての用語を大文字にします。 (例: "Clear-ItemProperty")。

パラメーター設計ガイドライン (SD03)

コマンドレットには、操作する必要があるデータを受け取るパラメーターと、操作の特性を決定するために使用される情報を示すパラメーターが必要です。 たとえば、コマンドレットにはパイプラインからデータを受け取る Name パラメーターがあり、コマンドレットの操作を強制的に実行できることを示す Force パラメーターがある場合があります。 コマンドレットで定義できるパラメーターの数に制限はありません。

標準パラメーター名を使用する

コマンドレットでは、ユーザーが特定のパラメーターの意味をすばやく判断できるように、標準のパラメーター名を使用する必要があります。 より具体的な名前が必要な場合は、標準のパラメーター名を使用し、エイリアスとしてより具体的な名前を指定します。 たとえば、 Get-Service コマンドレットには、ジェネリック名 (Name) とより具体的なエイリアス (ServiceName) を持つパラメーターがあります。 両方の用語を使用してパラメーターを指定できます。

パラメーター名とそのデータ型の詳細については、「 コマンドレット パラメーター名と機能ガイドライン」を参照してください。

単一パラメーター名を使用する

値が 1 つの要素であるパラメーターには複数形の名前を使用しないでください。 これには、ユーザーが配列またはリストに要素を 1 つだけ指定できるため、配列またはリストを受け取るパラメーターが含まれます。

複数のパラメーター名は、パラメーターの値が常に複数要素の値である場合にのみ使用する必要があります。 このような場合、コマンドレットは複数の要素が指定されていることを確認し、複数の要素が指定されていない場合は、ユーザーに警告を表示する必要があります。

パラメーター名にパスカル ケースを使用する

パラメーター名にはPascalケースを使用します。 つまり、パラメーター名の各単語の最初の文字 (名前の最初の文字を含む) を大文字にします。 たとえば、パラメーター名 ErrorAction では正しい大文字と小文字が使用されます。 次のパラメーター名では、不適切な大文字と小文字が使用されます。

  • errorAction
  • erroraction

オプションの一覧を取得するパラメーター

一連のオプションから値を選択できるパラメーターを作成するには、2 つの方法があります。

  • 有効な値を指定する列挙型を定義する (または既存の列挙型を使用する)。 次に、列挙型を使用して、その型のパラメーターを作成します。

  • パラメーター宣言に ValidateSet 属性を追加します。 この属性の詳細については、「 ValidateSet 属性宣言」を参照してください。

パラメーターに標準型を使用する

他のコマンドレットとの一貫性を確保するには、可能な限りパラメーターに標準の型を使用します。 さまざまなパラメーターに使用する必要がある型の詳細については、「 標準コマンドレットパラメーターの名前と型」を参照してください。 このトピックでは、"アクティビティ パラメーター" など、標準パラメーターのグループの名前と .NET Framework 型について説明するいくつかのトピックへのリンクを示します。

Strongly-Typed の .NET Framework 型を使用する

パラメーターの検証を改善するには、パラメーターを .NET Framework 型として定義する必要があります。 たとえば、一連の値から 1 つの値に制限されるパラメーターは、列挙型として定義する必要があります。 Uri (Uniform Resource Identifier) 値をサポートするには、 パラメーターを System.Uri 型として定義します。 自由形式のテキスト プロパティ以外のすべての基本的な文字列パラメーターは使用しないでください。

一貫性のあるパラメーター型を使用する

複数のコマンドレットで同じパラメーターを使用する場合は、常に同じパラメーター型を使用します。 たとえば、 Process パラメーターが 1 つのコマンドレット の System.Int16 型の場合、別のコマンドレットの Process パラメーターを System.Uint16 型にしないでください。

True と False を受け取るパラメーター

パラメーターが true と falseのみを受け取る場合は、パラメーターを System.Management.Automation.SwitchParameter 型として定義します。 switch パラメーターは、コマンドで指定されたときに true として扱われます。 パラメーターがコマンドに含まれていない場合、Windows PowerShell はパラメーターの値を falseと見なします。 ブール型のパラメーターは定義しないでください。

パラメーターで 3 つの値 ($true、$false、および "unspecified" を区別する必要がある場合は、Nullable<bool> 型のパラメーターを定義します。 通常、3 番目の "未指定" 値が必要になるのは、コマンドレットがオブジェクトの Boolean プロパティを変更できる場合です。 この場合、「未指定」とは、プロパティの現在の値を変更しないことを意味します。

パラメーターの配列のサポート

多くの場合、ユーザーは複数の引数に対して同じ操作を実行する必要があります。 これらのユーザーの場合、ユーザーが Windows PowerShell 変数としてパラメーターに引数を渡すことができるように、コマンドレットはパラメーター入力として配列を受け入れる必要があります。 たとえば、 Get-Process コマンドレットは、取得するプロセスの名前を識別する文字列の配列を使用します。

PassThru パラメーターをサポートする

既定では、 Stop-Process コマンドレットなど、システムを変更する多くのコマンドレットはオブジェクトの "シンク" として機能し、結果は返されません。 これらのコマンドレットは、 PassThru パラメーターを実装して、コマンドレットがオブジェクトを返すように強制する必要があります。 PassThru パラメーターを指定すると、コマンドレットは System.Management.Automation.Cmdlet.WriteObject メソッドの呼び出しを使用してオブジェクトを返します。 たとえば、次のコマンドは Calc (CalculatorApp.exe) を停止し、結果のプロセスをパイプラインに渡します。

Stop-Process -Name CalculatorApp -PassThru

ほとんどの場合、Add、Set、New コマンドレットは、 PassThru パラメーターをサポートする必要があります。

サポート パラメーター セット

コマンドレットは、単一の目的を達成することを目的としています。 ただし、操作または操作ターゲットを記述する方法は複数ある場合があります。 たとえば、プロセスは、その名前、識別子、またはプロセス オブジェクトによって識別される場合があります。 コマンドレットは、ターゲットのすべての妥当な表現をサポートする必要があります。 通常、コマンドレットは、一緒に動作するパラメーターセット (パラメーター セットと呼ばれます) を指定することで、この要件を満たします。 1 つのパラメーターは、任意の数のパラメーター セットに属できます。 パラメーター セットの詳細については、「コマンドレット パラメーター セットの」を参照してください。

パラメーター セットを指定する場合は、セット内の 1 つのパラメーターのみを ValueFromPipeline に設定します。 Parameter 属性を宣言する方法の詳細については、「ParameterAttribute 宣言」を参照してください。

パラメーター セットを使用する場合、既定のパラメーター セットは コマンドレット 属性によって定義されます。 既定のパラメーター セットには、対話型の Windows PowerShell セッションで使用される可能性が最も高いパラメーターを含める必要があります。 コマンドレット属性を宣言する方法の詳細については、「CmdletAttribute 宣言」を参照してください。

ユーザーにフィードバックを提供する (SD04)

このセクションのガイドラインを使用して、ユーザーにフィードバックを提供します。 このフィードバックにより、ユーザーはシステムで何が発生しているのかを認識し、より適切な管理上の意思決定を行うことができます。

Windows PowerShell ランタイムを使用すると、ユーザーは基本設定変数を設定して、 Write メソッドへの各呼び出しからの出力を処理する方法を指定できます。 ユーザーは、システムが情報を表示する必要があるかどうかを決定する変数や、さらにアクションを実行する前にシステムがユーザーにクエリを実行する必要があるかどうかを決定する変数など、いくつかの基本設定変数を設定できます。

WriteWarning、WriteVerbose、および WriteDebug メソッドをサポートする

コマンドレットは、意図しない結果が発生する可能性のある操作を実行しようとしているときに 、System.Management.Automation.Cmdlet.WriteWarning メソッドを呼び出す必要があります。 たとえば、コマンドレットが読み取り専用ファイルを上書きしようとしている場合は、コマンドレットでこのメソッドを呼び出す必要があります。

ユーザーがコマンドレットの実行内容に関する詳細を必要とする場合、コマンドレットは System.Management.Automation.Cmdlet.WriteVerbose メソッドを呼び出す必要があります。 たとえば、コマンドレットの作成者が、コマンドレットの動作に関する詳細情報を必要とする可能性があるシナリオがあると感じる場合は、この情報を呼び出す必要があります。

開発者または製品サポート エンジニアがコマンドレット操作の破損を理解する必要がある場合、このコマンドレットは System.Management.Automation.Cmdlet.WriteDebug メソッドを呼び出す必要があります。 Debug パラメーターには両方の情報セットが表示されるため、System.Management.Automation.Cmdlet.WriteDebug メソッドを System.Management.Automation.Cmdlet.WriteVerbose メソッドを呼び出すのと同じコードでコマンドレットを呼び出す必要はありません。

長い時間がかかる操作の WriteProgress をサポートする

完了に時間がかかり、バックグラウンドで実行できないコマンドレット操作では、 System.Management.Automation.Cmdlet.WriteProgress メソッドを定期的に呼び出して進行状況レポートをサポートする必要があります。

ホスト インターフェイスの使用

場合によっては、 System.Management.Automation.Cmdlet クラスでサポートされているさまざまな Write メソッドまたは Should メソッドを使用する代わりに、コマンドレットがユーザーと直接通信する必要があります。 この場合、コマンドレットは System.Management.Automation.PSCmdlet クラスから派生し、 System.Management.Automation.PSCmdlet.Host* プロパティを使用する必要があります。 このプロパティは、PromptForChoice、Prompt、WriteLine/ReadLine 型など、さまざまなレベルの通信の種類をサポートしています。 最も具体的なレベルでは、個々のキーの読み取りと書き込み、バッファーの処理を行う方法も提供されます。

コマンドレットがグラフィカル ユーザー インターフェイス (GUI) を生成するように特別に設計されていない限り、 System.Management.Automation.PSCmdlet.Host* プロパティを使用してホストをバイパスしないでください。 GUI を生成するように設計されたコマンドレットの例として、 Out-GridView コマンドレットがあります。

注

コマンドレットでは System.Console API を使用しないでください。

コマンドレット ヘルプ ファイルの作成 (SD05)

コマンドレット アセンブリごとに、コマンドレットに関する情報を含む Help.xml ファイルを作成します。 この情報には、コマンドレットの説明、コマンドレットのパラメーターの説明、コマンドレットの使用例などが含まれます。

コード ガイドライン

コマンドレットと他のコマンドレットを使用する間のユーザー エクスペリエンスの一貫性を確保するために、コマンドレットをコーディングする場合は、次のガイドラインに従う必要があります。 状況に適用されるコード ガイドラインが見つかると、同様のガイドラインに関する設計ガイドラインを必ず確認してください。

コーディング パラメーター (SC01)

Parameter 属性で修飾されたコマンドレット クラスのパブリック プロパティを宣言して、 パラメーター を定義します。 パラメーターは、コマンドレットの派生 .NET Framework クラスの静的メンバーである必要はありません。 Parameter 属性を宣言する方法の詳細については、「 パラメーター 属性の 宣言」を参照してください。

Windows PowerShell パスのサポート

Windows PowerShell パスは、名前空間へのアクセスを正規化するためのメカニズムです。 コマンドレットのパラメーターに Windows PowerShell パスを割り当てると、ユーザーは特定のパスへのショートカットとして機能するカスタム "ドライブ" を定義できます。 ユーザーがそのようなドライブを指定すると、レジストリ内のデータなどの格納されたデータを一貫した方法で使用できます。

コマンドレットでユーザーがファイルまたはデータ ソースを指定できる場合は、 System.String 型のパラメーターを定義する必要があります。 複数のドライブがサポートされている場合、型は配列である必要があります。 パラメーターの名前はPathであるべきで、別名はPSPathです。 さらに、 Path パラメーターはワイルドカード文字をサポートする必要があります。 ワイルドカード文字のサポートが必要ない場合は、 LiteralPath パラメーターを定義します。

コマンドレットが読み取りまたは書き込みを行うデータがファイルである必要がある場合、コマンドレットは Windows PowerShell パス入力を受け入れ、コマンドレットは System.Management.Automation.SessionState.Path プロパティを使用して、Windows PowerShell パスをファイル システムが認識するパスに変換する必要があります。 具体的なメカニズムには、次のメソッドが含まれます。

コマンドレットが読み取りまたは書き込むデータがファイルではなく文字列のセットである場合、コマンドレットはプロバイダー コンテンツ情報 (Content メンバー) を使用して読み取りと書き込みを行う必要があります。 この情報は、 System.Management.Automation.Provider.CmdletProvider.InvokeProvider プロパティから取得します。 これらのメカニズムにより、他のデータ ストアがデータの読み取りと書き込みに参加できるようになります。

ワイルドカード文字のサポート

可能であれば、コマンドレットでワイルドカード文字をサポートする必要があります。 ワイルドカード文字のサポートは、コマンドレットの多くの場所で行われます (特に、パラメーターが文字列を受け取って一連のオブジェクトから 1 つのオブジェクトを識別する場合)。 たとえば、StopProc チュートリアルのサンプル Stop-Proc コマンドレットでは、プロセス名を表す文字列を処理するName パラメーターが定義されています。 このパラメーターは、ユーザーが停止するプロセスを簡単に指定できるように、ワイルドカード文字をサポートします。

ワイルドカード文字のサポートが使用可能な場合、通常、コマンドレット操作では配列が生成されます。 場合によっては、ユーザーが一度に 1 つの項目のみを使用する可能性があるため、配列をサポートしても意味がありません。 たとえば、 Set-Location コマンドレットは、ユーザーが 1 つの場所のみを設定しているため、配列をサポートする必要はありません。 この例では、コマンドレットはワイルドカード文字を引き続きサポートしますが、解決を 1 つの場所に強制します。

ワイルドカード文字パターンの詳細については、「 コマンドレット パラメーターでのワイルドカード文字のサポート」を参照してください。

オブジェクトの定義

このセクションでは、コマンドレットのオブジェクトを定義したり、既存のオブジェクトを拡張したりするためのガイドラインについて説明します。

標準メンバーの定義

標準メンバーを定義して、カスタム Types.ps1xml ファイル内のオブジェクト型を拡張します (テンプレートとして Windows PowerShell Types.ps1xml ファイルを使用します)。 標準メンバーは、PSStandardMembers という名前のノードによって定義されます。 これらの定義を使用すると、他のコマンドレットと Windows PowerShell ランタイムが一貫した方法でオブジェクトを操作できます。

パラメーターとして使用する ObjectMember を定義する

コマンドレットのオブジェクトを設計する場合は、そのメンバーが、それを使用するコマンドレットのパラメーターに直接マップされていることを確認します。 このマッピングにより、オブジェクトをパイプラインに簡単に送信し、コマンドレット間で渡すことができます。

コマンドレットによって返される既存の .NET Framework オブジェクトには、スクリプト開発者またはユーザーが必要とする重要なメンバーや便利なメンバーが不足している場合がよくあります。 これらの不足しているメンバーは、オブジェクトをパイプラインに正しく渡すことができるように、表示と正しいメンバー名の作成に特に重要です。 これらの必須メンバーを文書化するカスタム Types.ps1xml ファイルを作成します。 このファイルを作成するときは、次の名前付け規則をお勧めします: <Your_Product_Name>。Types.ps1xml。

たとえば、 Mode スクリプト プロパティを System.IO.FileInfo 型に追加して、ファイルの属性をより明確に表示できます。 さらに、system.Array 型にCountエイリアス プロパティを追加して、(Lengthではなく) そのプロパティ名を一貫して使用できるようにすることもできます。

IComparable インターフェイスを実装する

すべての出力オブジェクトに System.IComparable インターフェイスを実装します。 これにより、出力オブジェクトをさまざまな並べ替えおよび分析コマンドレットに簡単にパイプできます。

表示情報の更新

オブジェクトの表示で期待される結果が得られない場合は、カスタム <YourProductName>を作成します。そのオブジェクトの Format.ps1xml ファイル。

適切に定義されたパイプライン入力のサポート (SC02)

パイプラインの中間に実装する

パイプラインの途中から呼び出されることを想定してコマンドレットを実装します (つまり、他のコマンドレットが入力を生成するか、出力を使用します)。 たとえば、 Get-Process コマンドレットはデータを生成するため、パイプラインの最初のコマンドレットとしてのみ使用されているとします。 ただし、このコマンドレットはパイプラインの途中用に設計されているため、このコマンドレットを使用すると、パイプライン内の以前のコマンドレットまたはデータで取得するプロセスを指定できます。

パイプラインからの入力のサポート

コマンドレットの各パラメーター セットに、パイプラインからの入力をサポートするパラメーターを少なくとも 1 つ含めます。 パイプライン入力のサポートにより、ユーザーはデータまたはオブジェクトを取得し、それらを正しいパラメーター セットに送信し、結果をコマンドレットに直接渡すことができます。

パラメーター属性に ValueFromPipeline キーワード、ValueFromPipelineByPropertyName キーワード属性、またはその宣言の両方のキーワードが含まれている場合、パラメーターはパイプラインからの入力を受け入れます。 パラメーター セット内のどのパラメーターも ValueFromPipeline キーワードまたは ValueFromPipelineByPropertyName キーワードをサポートしていない場合、パイプライン入力が無視されるため、コマンドレットを別のコマンドレットの後に置くことはできません。

ProcessRecord メソッドのサポート

パイプラインで前のコマンドレットのすべてのレコードを受け入れるには、コマンドレットで System.Management.Automation.Cmdlet.ProcessRecord メソッドを実装する必要があります。 Windows PowerShell は、コマンドレットに送信されるすべてのレコードに対して、このメソッドを複数回呼び出します。

パイプラインへの単一レコードの書き込み (SC03)

コマンドレットがオブジェクトを返す場合、コマンドレットは、生成されたオブジェクトをすぐに書き込む必要があります。 組み合わされた配列にバッファーするために、コマンドレットはそれらを保持しないでください。 入力としてオブジェクトを受け取るコマンドレットは、出力オブジェクトを遅延なく処理、表示、または処理し、表示することができます。 出力オブジェクトを一度に 1 つずつ生成するコマンドレットは 、System.Management.Automation.Cmdlet.WriteObject メソッドを呼び出す必要があります。 出力オブジェクトをバッチで生成するコマンドレット (基になる API が出力オブジェクトの配列を返すなど) は、 System.Management.Automation.Cmdlet.WriteObject メソッドを呼び出し、2 番目のパラメーターを true に設定する必要があります。

コマンドレットを大文字と小文字を区別し、大文字と小文字を保持するものにする (SC04)

既定では、Windows PowerShell 自体では大文字と小文字が区別されません。 ただし、多くの既存のシステムを扱うため、Windows PowerShell では操作と互換性を容易にするためにケースが保持されます。 つまり、文字が大文字で指定されている場合、Windows PowerShell では大文字が保持されます。 システムが適切に動作するためには、コマンドレットがこの規則に従う必要があります。 可能であれば、大文字と小文字を区別しない方法で動作する必要があります。 ただし、コマンドまたはパイプラインで後から発生するコマンドレットの元のケースは保持する必要があります。

こちらもご覧ください

必要な開発ガイドライン

アドバイザリ開発ガイドライン

Windows PowerShell コマンドレット の作成