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

  • [アーティクル]

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

設計ガイドライン

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

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

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

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

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

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

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

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

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

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

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

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

コードのガイドライン

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

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

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

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

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

コマンドレット名と一致するようにコマンドレットクラスの名前を指定します

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

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

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

停止要求を処理するには、StopProcessing メソッド (AC03) をオーバーライドします。

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

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

コマンドレット に、( パイプラインに書き込まれる) の破棄されないオブジェクトが含まれている場合、コマンドレットでは追加のオブジェクトの破棄が必要になることがあります。 たとえば、コマンドレットが、その システム のファイルハンドルを開いて、そのハンドルを開いたままにして 、プロセスの 終了時にハンドルを開いたままにした場合、このハンドルを閉じておく必要があるとします。

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

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

リモートコンピューターでコマンドレットを実行できるようにするには、クライアントコンピューターで簡単にシリアル化できる型を使用し、その後でサーバーコンピューター上で復元することができます。 次の型はシリアル化に適しています。

プリミティブ型:

  • Byte、SByte、Decimal、Single、Double、Int16、Int32、Int64、Uint16、UInt32、および UInt64。

  • ブール値、Guid、Byte []、TimeSpan、DateTime、Uri、Version。

  • Char、String、XmlDocument。

組み込みの rehydratable 型:

  • PSPrimitiveDictionary

  • SwitchParameter

  • PSListModifier

  • PSCredential

  • IPAddress、MailAddress

  • CultureInfo

  • X509Certificate2、System.security.cryptography.x509certificates.x500distinguishedname

  • DirectorySecurity、System.security.accesscontrol.filesecurity、RegistrySecurity

その他の種類:

  • SecureString

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

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

機微なデータを処理するときは、常に Securestring データ型を使用します。 これには、パラメーターへのパイプライン入力だけでなく、機密データをパイプラインに返すこともできます。

参照

必要な開発ガイドライン

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

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