次の方法で共有

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

このセクションでは、優れた開発とユーザー エクスペリエンスを確保するために考慮する必要があるガイドラインについて説明します。 適用される場合もあれば、適用されない場合もあります。

設計ガイドライン

コマンドレットを設計するときは、次のガイドラインを考慮する必要があります。 状況に適用される設計ガイドラインが見つかると、同様のガイドラインについては必ずコード ガイドラインを参照してください。

InputObject パラメーターのサポート (AD01)

Windows PowerShell は Microsoft .NET Framework オブジェクトと直接連携するため、多くの場合、ユーザーが特定の操作を実行するために必要な型と完全に一致する .NET Framework オブジェクトを使用できます。 InputObject は、このようなオブジェクトを入力として受け取るパラメーターの標準名です。 たとえば、Stop-Procのサンプル コマンドレットは、パイプラインからの入力をサポートする Process 型のInputObject パラメーターを定義します。 ユーザーは、一連のプロセス オブジェクトを取得し、それらを操作して停止する正確なオブジェクトを選択し、 Stop-Proc コマンドレットに直接渡すことができます。

Force パラメーターのサポート (AD02)

場合によっては、コマンドレットは、要求された操作を実行しないようにユーザーを保護する必要があります。 このようなコマンドレットは、ユーザーが操作を実行するアクセス許可を持っている場合に、ユーザーがその保護をオーバーライドできるようにする Force パラメーターをサポートする必要があります。

たとえば、 Remove-Item コマンドレットは通常、読み取り専用ファイルを削除しません。 ただし、このコマンドレットは Force パラメーターをサポートしているため、ユーザーは読み取り専用ファイルを強制的に削除できます。 ユーザーが既に読み取り専用属性を変更する権限を持っていて、ユーザーがファイルを削除した場合、 Force パラメーターを使用すると操作が簡略化されます。 ただし、ユーザーにファイルを削除するアクセス許可がない場合、 Force パラメーターは無効です。

Windows PowerShell (AD03) を使用して資格情報を処理する

コマンドレットでは、資格情報を表す Credential パラメーターを定義する必要があります。 このパラメーターは System.Management.Automation.PSCredential 型である必要があり、Credential 属性宣言を使用して定義する必要があります。 このサポートでは、完全な資格情報が直接指定されていない場合は、ユーザー名、パスワード、またはその両方の入力をユーザーに自動的に求めます。 Credential 属性の詳細については、「 資格情報属性の宣言」を参照してください。

エンコード パラメーターのサポート (AD04)

ファイル システム内のファイルへの書き込みやファイルからの読み取りなど、バイナリ 形式との間でテキストの読み取りまたは書き込みを行うコマンドレットの場合、バイナリ形式でテキストをエンコードする方法を指定する Encoding パラメーターがコマンドレットに必要です。

テスト コマンドレットはブール値を返す必要があります (AD05)

リソースに対してテストを実行するコマンドレットは、条件付き式で使用できるように 、System.Boolean 型をパイプラインに返す必要があります。

コード ガイドライン

コマンドレット コードを記述するときは、次のガイドラインを考慮する必要があります。 状況に適用されるガイドラインが見つかると、同様のガイドラインに関する設計ガイドラインを必ず確認してください。

コマンドレット クラスの名前付け規則 (AC01) に従う

標準の名前付け規則に従うことで、コマンドレットをより検出しやすくし、ユーザーがコマンドレットの動作を正確に理解できるようにします。 コマンドレットはパブリック型であるため、この方法は Windows PowerShell を使用する他の開発者にとって特に重要です。

正しい名前空間でコマンドレットを定義する

通常、コマンドレットを実行する製品を表す名前空間に .Commands を追加する .NET Framework 名前空間のコマンドレットのクラスを定義します。 たとえば、Windows PowerShell に含まれるコマンドレットは、 Microsoft.PowerShell.Commands 名前空間で定義されます。

コマンドレット名に一致するようにコマンドレット クラスに名前を付ける

コマンドレットを実装する .NET Framework クラスに名前を付ける場合は、 <Verb><Noun>Commandクラスに名前を付けます。ここで、 <Verb> と <Noun> のプレースホルダーをコマンドレット名に使用される動詞と名詞に置き換えます。 たとえば、 Get-Process コマンドレットは、 GetProcessCommandというクラスによって実装されます。

パイプライン入力が BeginProcessing メソッドをオーバーライドしない場合 (AC02)

コマンドレットがパイプラインからの入力を受け入れない場合は、 System.Management.Automation.Cmdlet.BeginProcessing メソッドに処理を実装する必要があります。 このメソッドを使用すると、Windows PowerShell でコマンドレット間の順序を維持できます。 パイプラインの最初のコマンドレットは、パイプライン内の残りのコマンドレットが処理を開始する前に、常にそのオブジェクトを返します。

Stop Requests を処理するには StopProcessing メソッドをオーバーライドします (AC03)

コマンドレットが停止シグナルを処理できるように、 System.Management.Automation.Cmdlet.StopProcessing メソッドを オーバーライドします。 一部のコマンドレットは、操作の完了に時間がかかり、実行時間の長い RPC 呼び出しでスレッドがブロックされている場合など、Windows PowerShell ランタイムの呼び出し間で長い時間が経過します。 これには、 System.Management.Automation.Cmdlet.WriteObject メソッド、 System.Management.Automation.Cmdlet.WriteError メソッド、および完了に時間がかかる可能性があるその他のフィードバック メカニズムを呼び出すコマンドレットが含まれます。 このような場合、ユーザーはこれらのコマンドレットに停止シグナルを送信する必要があります。

IDisposable インターフェイス (AC04) を実装する

System.Management.Automation.Cmdlet.ProcessRecord メソッドによって破棄されない (パイプラインに書き込まれた) オブジェクトがコマンドレットに含まれている場合、コマンドレットで追加のオブジェクト破棄が必要になる場合があります。 たとえば、コマンドレットが System.Management.Automation.Cmdlet.BeginProcessing メソッドでファイル ハンドルを開き、そのハンドルを System.Management.Automation.Cmdlet.ProcessRecord メソッドで使用できるように開いたままにしている場合、このハンドルは処理の終了時に閉じる必要があります。

Windows PowerShell ランタイムは、 常に System.Management.Automation.Cmdlet.EndProcessing メソッドを 呼び出すとは限りません。 たとえば、 System.Management.Automation.Cmdlet.EndProcessing メソッドは、コマンドレットが操作の途中で取り消された場合や、コマンドレットの一部で終了エラーが発生した場合に呼び出されない場合があります。 そのため、オブジェクトのクリーンアップを必要とするコマンドレットの .NET Framework クラスは、ファイナライザーを含む完全 な System.IDisposable インターフェイス パターンを実装する必要があります。そのため、Windows PowerShell ランタイムは、処理の最後に System.Management.Automation.Cmdlet.EndProcessing メソッドと System.IDisposable.Dispose* メソッドの両方を呼び出すことができます。

シリアル化に対応したパラメーター型の使用 (AC05)

リモート コンピューターでのコマンドレットの実行をサポートするには、クライアント コンピューターでシリアル化し、サーバー コンピューターでリハイドレートできる型を使用します。 次の型はシリアル化に対応しています。

プリミティブ型:

  • Byte、SByte、Decimal、Single、Double、Int16、Int32、Int64、Uint16、UInt32、UInt64。
  • Boolean、Guid、Byte[]、TimeSpan、DateTime、Uri、Version。
  • Char、String、XmlDocument。

組み込みのリハイドレート可能な型:

  • PSPrimitiveDictionary
  • スイッチパラメーター
  • PSListModifier
  • PSCredential
  • IPAddress、MailAddress
  • CultureInfo
  • X509Certificate2、X500DistinguishedName
  • DirectorySecurity、FileSecurity、RegistrySecurity

その他の種類:

  • セキュアストリング
  • コンテナー (上記の種類のリストとディクショナリ)

機密データに SecureString を使用する (AC06)

機密データを処理する場合は、常に System.Security.SecureString データ型を使用します。 これには、パラメーターへのパイプライン入力や、パイプラインへの機密データの返しが含まれる場合があります。

.NET では新しい開発に SecureString を使用することを推奨していますが、PowerShell は下位互換性のために引き続き SecureString クラスをサポートします。 SecureString の使用は、プレーンテキスト文字列を使用するよりも安全です。 PowerShell は、コンソールまたはログにコンテンツが誤って公開されないように、 SecureString 型に引き続き依存しています。 SecureString はプレーン テキスト文字列に簡単に変換できるため、慎重に使用してください。 SecureString の使用についての完全な議論は、「System.Security.SecureString クラス」ドキュメントを参照してください。

こちらもご覧ください

必要な開発ガイドライン

強く推奨される開発ガイドライン

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