次の方法で共有

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

  • [アーティクル]

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

設計ガイドライン

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

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

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

ユーザー エクスペリエンスを向上するには、コマンドレット名に対して選択する名詞を単数形にしてください。 たとえば、 の代わりに 名前 Get-Process を使用します Get-Processes 。 コマンドレットが複数の項目に対して実行される可能性がある場合でも、すべてのコマンドレット名に対してこの規則に従うのが最善です。

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

パラメーター名には Pascal の大文字と小文字を使用します。 つまり、動詞の最初の文字と名詞で使用される用語を大文字にしてください。 (例: "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 型として定義 します。 自由形式のテキスト プロパティを含むすべての基本的な文字列パラメーターは使用しないようにします。

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

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

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

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

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

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

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

PassThru パラメーターのサポート

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

Stop-Process calc -passthru

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

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

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

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

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

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

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

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

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

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

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

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

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

完了までに時間がかかり、バックグラウンドで実行できないコマンドレット操作は、 システム の定期的な呼び出しによる進行状況の報告をサポートする必要があります。

ホストインターフェイスを使用する

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

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

注意

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

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

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

コードのガイドライン

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

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

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

Windows PowerShell パスのサポート

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

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

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

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

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

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

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

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

オブジェクトの定義

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

標準メンバーの定義

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

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

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

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

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

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

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

表示情報の更新

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

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

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

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

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

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

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

ProcessRecord メソッドのサポート

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

1つのレコードをパイプラインに書き込む (SC03)

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

コマンドレットの Case-Insensitive と Case-Preserving (SC04) を作成する

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

参照

必要な開発ガイドライン

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

Windows PowerShell コマンドレットの記述