PowerShell Invoke-Command：包括的なガイド – techsyncer

ITのプロフェッショナルは、ほとんどの場合、ローカルコンピューターだけで作業することはありません。PowerShellのInvoke-Commandコマンドレットを使用すると、その必要はありません！このコマンドレットを使用すると、ローカルコンピューターで作業しているかのようにコードをシームレスに書くことができます。

PowerShellのリモート機能を使用することで、Invoke-Commandコマンドレットは一般的に使用されるPowerShellコマンドレットであり、ユーザーはPSSession内でコードを実行することができます。このPSSessionは、以前にNew-PSSessionコマンドレットで作成されたものであるか、一時的なセッションを迅速に作成して解除することもできます。

関連記事： PowerShellリモート操作：究極のガイド

Invoke-CommandをPowerShellのpsexecと考えてみてください。実装方法は異なりますが、コンセプトは同じです。少しのコードやコマンドを取り、それをリモートコンピューター上で「ローカル」に実行します。

ただし、Invoke-Commandを使用するには、リモートコンピューターでPowerShellリモートが有効になっている必要があります。デフォルトでは、すべてのWindows Server 2012 R2以降のマシンには、それと適切なファイアウォールの例外が有効になっています。Server 2008のマシンを使用している場合は、複数の方法でリモート操作を設定することができますが、簡単な方法は、リモートマシンで「winrm quickconfig」または「Enable-PSRemoting」を実行することです。

「Invoke-Command」が「ad-hocコマンド」と一緒に動作する方法を示すために、リモートのWindows Server 2012 R2以降のドメイン参加コンピューターがあるとしましょう。ワークグループのコンピューターで作業する場合は少し複雑になります。 PowerShellコンソールを開き、「Invoke-Command」と入力してエンターキーを押します。

PS> Invoke-Command
cmdlet Invoke-Command at command pipeline position 1
Supply values for the following parameters:
ScriptBlock:

I’m immediately asked to provide a scriptblock. The scriptblock is the code that we’re going to run on the remote computer.

スクリプトブロック内のコードがリモートコンピューターで実行されることを証明するために、「hostname」コマンドを実行してみましょう。このコマンドは、実行されているコンピューターのホスト名を返します。ローカルコンピューターで「hostname」を実行すると、その名前が表示されます。

PS> hostname
MACWINVM

次に、同じコードを含むスクリプトブロックを「Invoke-Command」に渡してみましょう。ただし、忘れている必要なパラメーターがあります：「ComputerName」です。「Invoke-Command」に、このコマンドを実行するリモートコンピューターを指定する必要があります。

PS> Invoke-Command -ScriptBlock { hostname } -ComputerName WEBSRV1 WEBSRV1

hostnameの出力が、リモートコンピューターの名前WEBSRV1になっていることに注意してください。あなたはWEBSRV1でコードを実行しました。スクリプトブロック内に単純なコードを実行し、単一のリモートマシンに渡すことは、Invoke-Commandの最も簡単な応用ですが、それ以上のこともできます。

ローカル変数をリモートスクリプトブロックに渡す

スクリプト内には、Invoke-Commandの参照は1つだけではありません。スクリプトはおそらく数十行にわたり、変数が定義されたり、モジュールで関数が定義されたりするでしょう。ただいくつかのコードを中括弧で括るだけのように見えるかもしれませんが、実際にはそのコードが実行されるスコープ全体が変わってしまいます。なぜなら、そのコードはリモートコンピュータに送信されるからです。リモートコンピュータは、スクリプトブロック内のローカルのコードに関して、スクリプト内に含まれるもの以外の情報を持っていません。

例えば、コンピュータ名とファイルパスのパラメータを持つ関数があるかもしれません。この関数の目的は、リモートコンピュータ上でいくつかのソフトウェアインストーラを実行することです。リモートコンピュータ上にすでに存在する「ローカル」ファイルパスをインストーラに渡すことができます。

以下の関数は合理的なように見えますね。実行してみましょう。

function Install-Stuff {
    param(
    	[Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$ComputerName,
        
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$InstallerFilePath
	)
    Invoke-Command -ComputerName $ComputerName -ScriptBlock { & $InstallerFilePath }
}

PS> Install-Stuff -ComputerName websrv1 -InstallerFilePath 'C:\install.exe'
The expression after '&' in a pipeline element produced an object that was not valid. It must result in a command name, a script block, or a CommandInfo object.
+ CategoryInfo          : InvalidOperation: (:) [], RuntimeException
+ FullyQualifiedErrorId : BadExpression
+ PSComputerName        : websrv1

しかし、エラーメッセージが表示され、エラーが発生します。アンパサンド演算子の使用によるものです。コード自体は間違っていませんが、関数のパラメータで値を渡したにもかかわらず、$InstallerFilePathが空であったため失敗しました。アンパサンドをWrite-Hostと置き換えてテストできます。

新しい関数の行: Invoke-Command -ComputerName $ComputerName -ScriptBlock { Write-Host "Installer path is: $InstallerFilePath" }

PS> Install-Stuff -ComputerName websrv1 -InstallerFilePath 'C:\install.exe'
Installer path is:
PS>

$InstallerFilePathの値が空です。変数はリモートマシンに渡されなかったため、展開されていません。ローカルで定義された変数をリモートのスクリプトブロックに渡すには、2つのオプションがあります。スクリプトブロック内で変数名の前に$using:を付けるか、Invoke-CommandのArgumentListパラメーターを使用することができます。両方を見てみましょう。

ArgumentListパラメーター

ローカル変数をリモートのスクリプトブロックに渡す方法の1つは、Invoke-CommandのArgumentListパラメーターを使用することです。このパラメーターを使用すると、ローカル変数をパラメーターに渡し、スクリプトブロック内のローカル変数の参照をプレースホルダーで置き換えることができます。

ArgumentListパラメーターにローカル変数を渡すのは簡単です。

Invoke-Command -ComputerName WEBSRV1 -ScriptBlock { & $InstallerFilePath } -ArgumentList $InstallerFilePath

問題になるのは、スクリプトブロック内の変数の構造です。 { & $InstallerPath }の代わりに、{ & $args[0] }または{param($foo) & $foo }に変更する必要があります。どちらを使用すべきでしょうか？

ArgumentListパラメーターはオブジェクトのコレクションです。オブジェクトのコレクションを使用すると、一度に1つ以上のオブジェクトを渡すことができます。この場合、私は単に1つのオブジェクトを渡しています。

実行されると、Invoke-Commandコマンドレットはそのコレクションを取得し、それをスクリプトブロックに注入して、実質的に$argsという配列に変換します。ここで、$args -eq ArgumentListであることを覚えておいてください。この時点で、配列と同様にコレクションの各インデックスを参照します。私たちの場合、コレクションには1つの要素（$InstallerFilePath）しかありませんでしたが、これは$args[0]、つまりそのコレクションの最初のインデックスを意味します。ただし、もしそれ以上の要素がある場合は、$args[1]、$args[2]などで参照します。

さらに、スクリプトブロックの変数により良い変数名を割り当てる場合は、関数のようにスクリプトブロックにパラメータを追加することもできます。結局のところ、スクリプトブロックは匿名関数です。スクリプトブロックのパラメータを作成するには、paramブロックを作成し、パラメータの名前を指定します。作成した後、スクリプトブロック内でそのパラメータを以下のように参照します。

Invoke-Command -ComputerName WEBSRV1 -ScriptBlock { param($foo) & $foo } -ArgumentList $InstallerFilePath

この場合、ArgumentListコレクションの要素は、定義されたパラメータに順番に「マッピング」されます。パラメータ名は重要ではありません。重要なのは順序です。Invoke-Commandは、ArgumentListコレクションの最初の要素を取り、最初のパラメータを検索してその値をマッピングし、同様に2番目、3番目などを行います。

$Using構文

$using構文は、ローカル変数をリモートのスクリプトブロックに渡すためのもう一つの一般的な方法です。この構文では、既存のローカル変数を再利用することができますが、変数名の前に$using:を付けるだけです。 $argsコレクションを心配する必要はありませんし、パラメータブロックを追加する必要もありません。

Invoke-Command -ComputerName WEBSRV1 -ScriptBlock { & $using:InstallerFilePath }

PowerShellの$using構文は非常にシンプルですが、Pesterを学ぶと、ArgumentListが便利なことがわかるでしょう。

Invoke-CommandとNew-PSSession

技術的には、この投稿はInvoke-Commandに関するものですが、その有用性を示すために、New-PSSessionコマンドにも簡単に触れる必要があります。以前に、Invoke-Commandは「アドホック」コマンドまたは既存のセッションを使用できると述べました。

この投稿では、リモートコンピュータで単発のコマンドを実行していました。新しいセッションを立ち上げ、コードを実行し、セッションを終了させていました。これは一度限りの状況では問題ありませんが、同じコンピュータで何十ものコマンドを実行する場合にはあまり適していません。この場合、事前にNew-PSSessionを使用して既存のPSSessionを再利用する方が良いです。

コマンドを実行する前に、New-PSSessionでPSSessionを作成する必要があります。これは、単純に$session = New-PSSession -ComputerName WEBSRV1を実行することで行うことができます。これにより、サーバー上でリモートセッションが作成され、ローカルマシン上でそのセッションへの参照が作成されます。この時点で、ComputerNameの参照をSessionに置き換え、Sessionを保存された$session変数に指定します。

Invoke-Command -Session $session -ScriptBlock { & $using:InstallerFilePath }

実行すると、セッションが既に構築されているため、パフォーマンスが向上することに気付くでしょう。ただし、完了したら、Remove-PSSessionでオープンセッションを削除することが重要です。

概要

Invoke-Command PowerShellのcmdletは、最も一般的で強力なcmdletの1つです。私自身、ほとんどのコマンドの中で最もよく使用するものです。使いやすさとリモートコンピュータで任意のコードを実行できる能力は非常に強力であり、このコマンドを上から下まで学ぶことをお勧めします！