コマンドレットにユーザーメッセージを追加する

[アーティクル]
2025-03-25

コマンドレットは、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 コマンドレットは、Name、Force、および PassThruの 3 つのパラメーターを定義します。これらのパラメーターの定義の詳細については、「システムを変更するコマンドレットの作成」を参照してください。

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 メモ帳

警告メッセージの書き込み

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 コマンドレットを作成する方法

オブジェクト型の拡張と書式設定の

コマンドレット、プロバイダー、およびホストアプリケーションを登録する方法

Windows PowerShell SDK の