コマンドレットにユーザー メッセージを追加する
コマンドレットは、ランタイムによってユーザーに表示できる複数の種類のメッセージWindows PowerShellできます。 これらのメッセージには、次の種類が含まれます。
一般的なユーザー情報を含む詳細メッセージ。
トラブルシューティング情報を含むメッセージをデバッグします。
予期しない結果になる可能性がある操作を実行するコマンドレットの通知を含む警告メッセージ。
長い時間がかかる操作を実行するときにコマンドレットが完了した作業量に関する情報を含む進行状況レポート メッセージ。
コマンドレットで書き込み可能なメッセージの数や、コマンドレットが書き込むメッセージの種類に制限はありません。 各メッセージは、コマンドレットの入力処理メソッド内から特定の呼び出しを行って書き込まれます。
コマンドレットの定義
コマンドレットの作成の最初の手順は、常にコマンドレットに名前を付け、コマンドレットを実装する .NET クラスを宣言します。 任意の種類のコマンドレットは、入力処理メソッドからユーザー通知を書き込む可能性があります。そのため、一般に、コマンドレットが実行するシステム変更を示す任意の動詞を使用して、このコマンドレットに名前を付けできます。 承認されたコマンドレット動詞の詳細については、「コマンドレット動詞名」 を参照してください。
このStop-Procは、システムを変更するように設計されています。したがって 、.NET クラスの System.Management.Automation.CmdletAttribute 宣言には 属性キーワードを含め、 を SupportsShouldProcess に設定する必要があります true 。
次のコードは、このコマンドレット クラスのStop-Procです。 この定義の詳細については、「システムを変更 するコマンドレットの作成」を参照してください。
[Cmdlet(VerbsLifecycle.Stop, "proc",
SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet
システム変更のパラメーターの定義
このStop-Proc、、および の 3 つの Name パラメーター Force を定義します PassThru 。 これらのパラメーターの定義の詳細については、「システムを変更 するコマンドレットの作成」を参照してください。
次に示すのは、Stop-Procコマンドレットのパラメーター宣言です。
[Parameter(
Position = 0,
Mandatory = true,
ValueFromPipeline = true,
ValueFromPipelineByPropertyName = true
)]
public string[] Name
{
get { return processNames; }
set { processNames = value; }
}
private string[] processNames;
/// <summary>
/// Specify the Force parameter that allows the user to override
/// the ShouldContinue call to force the stop operation. This
/// parameter should always be used with caution.
/// </summary>
[Parameter]
public SwitchParameter Force
{
get { return force; }
set { force = value; }
}
private bool force;
/// <summary>
/// Specify the PassThru parameter that allows the user to specify
/// that the cmdlet should pass the process object down the pipeline
/// after the process has been stopped.
/// </summary>
[Parameter]
public SwitchParameter PassThru
{
get { return passThru; }
set { passThru = value; }
}
private bool passThru;
入力処理メソッドのオーバーライド
コマンドレットは入力処理メソッドをオーバーライドする必要があります。ほとんどの場合は 、System.Management.Automation.Cmdlet.ProcessRecordになります。 このStop-Procは 、System.Management.Automation.Cmdlet.ProcessRecord 入力処理メソッドをオーバーライドします。 この Stop-Proc コマンドレットの実装では、詳細メッセージ、デバッグ メッセージ、および警告メッセージを書き込む呼び出しが行います。
注意
このメソッドが System.Management.Automation.Cmdlet.ShouldProcess メソッドと System.Management.Automation.Cmdlet.ShouldContinue メソッドを呼び出す方法の詳細については、「システムを変更するコマンドレットの作成」を参照 してください。
詳細メッセージの書き込み
System.Management.Automation.Cmdlet.WriteVerboseメソッドは、特定のエラー状態に関係のない一般的なユーザー レベルの情報を書き込むのに使用されます。 その後、システム管理者はその情報を使用して、他のコマンドの処理を続行できます。 さらに、このメソッドを使用して記述された情報は、必要に応じてローカライズする必要があります。
この Stop-Proc コマンドレットの次のコードは、System.Management.Automation.Cmdlet.ProcessRecordメソッドのオーバーライドからSystem.Management.Automation.Cmdlet.WriteVerboseメソッドを 2 回呼び出す方法を示しています。
message = String.Format("Attempting to stop process \"{0}\".", name);
WriteVerbose(message);
message = String.Format("Stopped process \"{0}\", pid {1}.",
processName, process.Id);
WriteVerbose(message);
デバッグ メッセージの書き込み
System.Management.Automation.Cmdlet.WriteDebugメソッドは、コマンドレットの操作のトラブルシューティングに使用できるデバッグ メッセージを記述するために使用されます。 呼び出しは、入力処理メソッドから行います。
注意
Windows PowerShellとデバッグの Debug 両方の情報を表示するパラメーターも定義します。 コマンドレットでこのパラメーターがサポートされている場合、System.Management.Automation.Cmdlet.WriteVerbose を呼び出すのと同じコードで System.Management.Automation.Cmdlet.WriteDebug を呼び出す 必要はありません。
サンプル Stop-Proc コマンドレットの次の 2 つのコード セクションでは、System.Management.Automation.Cmdlet.ProcessRecordメソッドのオーバーライドからのSystem.Management.Automation.Cmdlet.WriteDebugメソッドの呼び出しを示します。
このデバッグ メッセージは 、System.Management.Automation.Cmdlet.ShouldProcess が呼び出される直前に書き込まれます。
message =
String.Format("Acquired name for pid {0} : \"{1}\"",
process.Id, processName);
WriteDebug(message);
このデバッグ メッセージは 、System.Management.Automation.Cmdlet.WriteObject が呼び出される直前に書き込まれます。
message =
String.Format("Writing process \"{0}\" to pipeline",
processName);
WriteDebug(message);
WriteObject(process);
Windows PowerShell System.Management.Automation.Cmdlet.WriteDebug呼び出しをトレース インフラストラクチャとコマンドレットに自動的にルーティングします。 これにより、コマンドレット内で追加の開発作業を行わずに、メソッド呼び出しをホスティング アプリケーション、ファイル、またはデバッガーにトレースできます。 次のコマンド ライン エントリは、トレース操作を実装します。
PS> trace-expression stop-proc -file proc.log -command stop-proc notepad
警告メッセージの書き込み
System.Management.Automation.Cmdlet.WriteWarningメソッドは、読み取り専用ファイルの上書きなど、予期しない結果になる可能性がある操作をコマンドレットが実行する際に警告を書き込むときに使用されます。
サンプル Stop-Proc コマンドレットの次のコードは、System.Management.Automation.Cmdlet.ProcessRecordメソッドのオーバーライドからのSystem.Management.Automation.Cmdlet.WriteWarningメソッドの呼び出しを示しています。
if (criticalProcess)
{
message =
String.Format("Stopping the critical process \"{0}\".",
processName);
WriteWarning(message);
} // if (criticalProcess...
進行状況メッセージの書き込み
System.Management.Automation.Cmdlet.WriteProgress は、コマンドレット操作の完了に長い時間がかかる場合に進行状況メッセージを書き込むときに使用されます。 System.Management.Automation.Cmdlet.WriteProgressの呼び出しは、ユーザーにレンダリングするためにホスティング アプリケーションに送信されるSystem.Management.Automation.Progressrecordオブジェクトを渡します。
注意
この Stop-Proc、System.Management.Automation.Cmdlet.WriteProgress メソッドの呼び出しは含まれます。
次のコードは、項目のコピーを試みるコマンドレットによって書き込まれた進行状況メッセージの例です。
int myId = 0;
string myActivity = "Copy-item: Copying *.* to c:\abc";
string myStatus = "Copying file bar.txt";
ProgressRecord pr = new ProgressRecord(myId, myActivity, myStatus);
WriteProgress(pr);
pr.RecordType = ProgressRecordType.Completed;
WriteProgress(pr);
コード サンプル
完全な C# サンプル コードについては 、「StopProcessSample02 サンプル」を参照してください。
オブジェクトの種類と書式設定を定義する
Windows PowerShell.NET オブジェクトを使用してコマンドレット間で情報を渡します。 そのため、コマンドレットで独自の型を定義する必要がある場合や、別のコマンドレットによって提供される既存の型を拡張する必要がある場合があります。 新しい型の定義または既存の型の拡張の詳細については、「オブジェクト型の拡張」および「書式設定」 を参照してください。
コマンドレットの構築
コマンドレットを実装した後、 スナップインを使用してWindows PowerShellに登録Windows PowerShell必要があります。 コマンドレットの登録の詳細については、「コマンドレット、プロバイダー、およびホスト アプリケーションを登録する方法」 を参照してください。
コマンドレットのテスト
コマンドレットが Windows PowerShellに登録されている場合は、コマンド ラインで実行してテストできます。 コマンドレットのサンプルをStop-Procしましょう。 コマンド ラインからコマンドレットを使用する方法の詳細については、「 コマンド ラインを使用したはじめにをWindows PowerShell。
次のコマンド ライン エントリでは、Stop-Proc を使用して、"NOTEPAD" という名前のプロセスを停止し、詳細な通知を提供し、デバッグ情報を出力します。
PS> stop-proc -Name notepad -Verbose -Debug次のような出力が表示されます。
VERBOSE: Attempting to stop process " notepad ". DEBUG: Acquired name for pid 5584 : "notepad" Confirm Continue with this operation? [Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): Y Confirm Are you sure you want to perform this action? Performing operation "stop-proc" on Target "notepad (5584)". [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): Y VERBOSE: Stopped process "notepad", pid 5584.
参照
Windows PowerShell コマンドレットを作成する方法