RSS2.02012/12/01
PowerShellらしい関数の書き方 [PS Advent Calendar '12]
今日から、PowerShell Advent Calendar 2012が始まりました。初日は私が担当させていただきます。お題は旬の話題、PowerShell 3.0の新機能！…ではなく、初心に返って、PowerShellの「関数」ってどう書くのがいいのかというお話をします。PowerShell 3.0どころか、大部分はPowerShell 1.0から変わっていない基本の話です。
これは今までずっと書きたかったネタですがなかなか書く暇がなくて放置してたものです。3.0の話はきっと他の皆さんが書いて下さるはず！私もまた順番が回ってきたら書こうと思います。
PowerShellの関数は従来言語とだいぶ違う
PowerShellを使いこなすようになってくると、他の言語を使う時と同じで、定型処理は関数として一つにまとめたくなってきます。ところが他の言語と同じような感覚で関数を書くと、どうもうまくいかないのです。
たとえば引数にフォルダパスとフォルダ名を指定すると、指定フォルダが存在すればFalseを返し、存在しなければ作成してTrueを返す関数を書いてみました。
function MakeDir($path,$name)
{
$newDirPath = Join-Path $path $name
if((Test-Path $newDirPath))
{
return $false
}
else
{
New-Item -ItemType Directory -Path $newDirPath
return $true
}
}
実行は
MakeDir("C:\test","NewFolder")
と、メソッド風に呼び出すことはできないので、コマンドレット風に
MakeDir C:\test NewFolder
と呼び出せばいいんですが（まあ最初はここもつまづきポイントではありますが）、この実行結果は以下のようになります。
ディレクトリ: C:\test Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 2012/12/01 7:51 NewFolder True
フォルダが作成されてTrueが返却されることを想定していたのに、なんか余計な出力が混じってしまっています。なんでしょうこれは？
実はPowerShell関数内で値が出力されると、returnキーワードがついてなくてもすべて呼び出し元に出力されるという仕様なのです。そしてPowerShellにおけるreturnキーワードの効果は「後続処理を打ち切って呼び出し元に戻る。ただしreturnの後に値が指定してあればそれを最後の値として戻す」となります。そのため、呼び出し元に返したくない出力が関数内にある場合は、すべて[void]にキャストしたり|Out-Nullとしてリダイレクトするなどして出力を破棄する必要があるのです。このMakeDir関数の場合はNew-Itemコマンドレットが作成したフォルダのFolderInfoオブジェクトを出力するので、これをNew-Item -ItemType Directory -Path $newDirPath | Out-Null のように破棄してやる必要があるわけです。
パイプラインの動作
先ほどの例を見ると、「いやいやなんでそんな訳のわからない仕様なんだよ、returnあるときだけ値返せよ」とお思いかと思います。しかしこれはPowerShellの特長の一つである、コマンドのパイプラインによる連携を行うための仕様なんです。
ここでコマンドを繋ぐパイプラインがどういう動作をしてるか、おさらいします。
Get-Process | where {$_.Handles -ge 500} | foreach {$_.Path}
これはハンドル数が500以上のプロセスのメインモジュールファイルのパスを取得するというコマンドで、別に何の変哲もありません。ところが、このコマンドがやっている処理を、次のように誤解してませんでしょうか？
① 稼働中のすべてのプロセスの一覧を配列として取得する。
② ①で取得した配列を走査して、Handlesプロパティの値を調べる。Handlesが500以上のオブジェクトだけ抽出した配列を生成する。
③ ②で生成した配列を列挙して、{}内のスクリプトをそれぞれ実行する。
しかし、これは間違いです。
正しくは
① 稼働中の1つのプロセスオブジェクトを取得して次のコマンドへ送る。
② そのプロセスのハンドル数が500以上なら、次のコマンドへ送る。そうでないなら①に戻る。
③ そのプロセスに対して{}内のスクリプトを実行する。まだ未取得のプロセスが残っていれば①に戻る。
という動きをしています。つまり、パイプラインの手前で一旦すべての処理を終えてから、出力オブジェクトがまとめて配列という形で次のコマンドに送られるのではなく、オブジェクトがパイプラインの先頭から末尾に向けて1つずつ通過していき、それが先頭コマンドの出力オブジェクト数だけ繰り返される、という動作をしているのです。
これがPowerShellのパイプライン処理が、従来の処理系での関数と決定的に違うところで、パイプラインによって複数のコマンドが、あたかももとからあった単一のコマンドのように密に連携するわけです。
（この処理、.NETのLINQにちょっと似てると思う方もいらっしゃると思います。しかしLINQとは全然違うものです。なんせPowerShellはLINQより先に世に出てますし！ しかし類似点も多いのでいずれ比較なんかを書きたいと思ってます）
パイプラインで連携可能な関数の書き方
さて、先ほどのパイプラインの話ではコマンドレットを連携させていました。しかしPowerShellにおいてはコマンドレットも関数も、それが.NETのクラスかPowerShellのスクリプトなのかの違いがあるだけで、基本は同じ「コマンド」です。なので、関数もコマンドレットと同様、適切な記述をおこなえば、パイプラインでコマンド同士を連携させることが可能です。
以下に、Get-Repeatという関数の例を挙げます。この関数は-Textパラメータに文字列を指定し、-Countパラメータに回数を指定すると、指定文字列を指定回数分連結した文字列を出力する、という何の変哲もない関数です。しかしパイプラインからの入力を受け付け、次のパイプラインへ出力することを想定した作りになっています。
function Get-Repeat
{
param(
[Parameter(ValueFromPipeline=$true,Mandatory=$true)]
[string[]]
$Text,
[int]
$Count=2
)
begin
{
}
process
{
foreach($s in $Text)
{
$s * $count
}
}
end
{
}
}
以下は実行例です。
PS> Get-Repeat -Text ab -Count 2 abab PS> "ab" | Get-Repeat -Count 2 abab PS> Get-Repeat -Text ab,cd -Count 2 abab cdcd PS> "ab","cd" | Get-Repeat -Count 2 abab cdcd
このように、パラメータに値を指定してもパイプラインから入力しても、スカラー値（配列ではない単一のオブジェクト）でも配列でも、正しく処理されています。
この関数をポイントごとに見ていきましょう。
PowerShellの正式な関数はparam節、beginブロック、processブロック、endブロックに分かれます。param節にはパラメータを指定します。beginブロックにはパイプラインで連携した際、最初の1回だけ実行される初期化処理、endブロックには最後の1回だけ実行される後始末処理を記述します。beginとendは今回の例では内容を省略しています。processブロックには、パイプラインから入力された1つのオブジェクトに対してその都度実行される処理を記述します。
ちなみに、
コマンド①|コマンド②|コマンド③
とある場合、各コマンドにおけるbegin,process,endブロックは次のような順番で呼び出されます。
コマンド①begin→コマンド②begin→コマンド③begin→{コマンド①process→コマンド②process→コマンド③process→コマンド①process…}→コマンド①end→コマンド②end→コマンド③end
processブロックでの処理は、通常はパイプラインだけではなくパラメータからも値を入力できるようにしておきます。そのためにはparam節に記述するパラメータに「このパラメータはパイプラインから値を入力することもできる」を意味する[Parameter(ValueFromPipeline=$true)]という属性を指定します（この属性はPowerShell 2.0から利用可）。今回のパラメータには「このパラメータは必須である」を意味するMandatory=$trueもあわせて指定しています。
先述の通り、パイプラインから入力される場合は配列ではなくオブジェクトが単体で渡されるのですが、パラメータから入力される場合はスカラー値と配列値、どちらの可能性もあるため、[string[]] のようにパラメータの型を配列型にしておくことで、どちらを指定しても処理できるようにしています。
processブロックではパラメータ経由で配列値が渡された場合に、各要素に対して処理を行うためforeachループを設けています。ちなみにスカラー値が渡された場合もforeachは問題なく処理します。
processブロック内では、returnは記述しません。returnするとその時点で関数が終了してしまうので正しくすべての出力ができなくなってしまいます。
特にこの例の関数のように入力型と出力型が同一の場合は、processブロックでは1オブジェクトの入力に対して、1オブジェクトを出力するようにしておくと、他のコマンドと連携させやすくなります。ただしWhere-Objectコマンドレットのようにフィルタ処理を行う関数の場合は、条件によっては何も出力しないようにします(空の配列とか$nullを返すのではないことに注意)。もちろん入力オブジェクトから何らかの配列値を出力する場合もありえます。
最低限、これらのポイントを押さえて関数を記述すると、他のコマンドとパイプラインで連携しやすい、PowerShellらしい関数を書くことができると思います。
まとめ
PowerShellでは従来言語と同じ感覚で関数を書くと、うまくいかないことが多いです。もっとも単に処理をひとまとめにしたいというニーズだけならばそれでも問題ないのですが、関数同士を組み合わせたいときに問題が顕在化します。
パイプラインの真の動作を理解し、パイプラインの中に組み込んで動作させることを想定した関数を記述すると、他のコマンドレットあるいは自作関数と連携しやすくなり、PowerShellの真の力を解放することができると思います。
PowerShell Advent Calendar 2012の1日目にしてはえらい固いネタかもですが、基本をおさらいするのも大事ですよね。
さて、明日は@jsakamotoさんの番です。よろしくお願いします。
2011/12/02
バックグラウンドジョブの使い方・基本編 [PS Advent Calendar '11]
はじめに
このたび、技術系アドベントカレンダーイベントの1つとして、PowerShell Advent Calendar 2011を企画しました。この記事はその2日目の記事となります。アドベントカレンダーについてはリンク先を参照してください。
今日のテーマはPowerShellのバックグラウンドジョブ機能の使い方についてのまとめです。
バックグラウンドジョブとは
バックグラウンドジョブ機能はその名の通り、ジョブ（具体的にはスクリプト）をバックグラウンドで非同期に実行するものです。PowerShell v2で追加された機能の一つです。インタラクティブシェルでStart-Jobコマンドレットを使用してバックグラウンドジョブ（以下、単に「ジョブ」と表記）を実行すると、新しくpowershell.exeのプロセスが起動しそのままシェルに制御が戻りユーザーは後続の処理を行うことができます。もちろんスクリプトからジョブを実行することも可能です。時間のかかる処理をバックグラウンドで走らせたり、数多くの処理を並列で実行したりするのに重宝します。
起動されたジョブは操作中のpowershell.exeとは別のジョブ用のプロセスで実行され、処理が完了すると呼び出し元でその結果をReceive-Jobコマンドレットを使って受け取ることができます。ジョブは並列して何個も同時に実行できます。なおPowerShellのジョブは1ジョブ=1プロセスです。スレッドではないので注意。
PowerShellのジョブシステムはリモート処理インフラストラクチャの上に構築されているので、たとえローカルPCでもジョブ実行するにはローカルPCをリモート用構成にしておく必要があります。詳しくはabout_Remote_Requirementsを参照のこと。
ジョブはローカルでもリモートでも走らせることができます。以下に具体的な方法を述べていきます。
ローカルコンピュータでのジョブ実行
ローカルコンピュータ上に新しくジョブを作成して開始するにはStart-Jobコマンドレットを用います。
Start-Job {ジョブとして実行したいコマンド、スクリプト}
とするとジョブを実行します。
$job=Start-Job {..}
のようにするとJobオブジェクト（System.Management.Automation.PSRemotingJob）を変数に格納してあとで利用できます。変数で受けない場合はJobオブジェクトの内容が表示されます。
存在するジョブを取得するにはGet-Jobコマンドレットを用います。
Get-Job
で現在実行中のジョブ一覧を表示します。以下に出力例を示します。
Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 1 Job1 Completed True localhost "test" 3 Job3 Running True localhost start-sleep -sec 120;"...
以下の表は各項目の意味です。
| Id | ジョブID番号 |
| Name | ジョブの名前 |
| State |
Running=実行中のジョブ Stopped=停止したジョブ Complete=完了したジョブ Failed=エラーが出たジョブ |
| HasMoreData | 返却されたデータがあるかどうか |
| Location | ジョブが実行されているコンピュータ名 |
| Command | ジョブで実行されているコマンド、スクリプト |
ジョブの終了を待つにはWait-Jobコマンドレットを用います。
Get-Job|Wait-Job
とすると実行中のジョブすべてが完了するまで待ちます。-timeoutパラメータを使うと最大待ち時間（秒）を指定できます。
Get-Job|Wait-Job -any
とすると実行中のいずれかのジョブが完了するまで待ちます。正確には「対象のジョブが一つ以上完了するまで待つ」という効果なので、完了済みのジョブが1つ以上ある場合に新たにジョブを追加した場合などは想定の動作になりません。あらかじめRemove-Jobで完了済みのジョブを削除するか、Where-ObjectコマンドレットでRunningのみ対象にするようフィルタをかけるかしてください。
ジョブを中止するにはStop-Jobコマンドレットを用います。
Get-Job -id 1|Stop-Job
とするとジョブIDが1のジョブを中止します。
$jobにJobオブジェクトが格納されている場合は
$job|Stop-Job
でもOKです。
ジョブを削除するにはRemove-Jobコマンドレットを用います。
Get-Job|where {$_.state -eq "Completed" -or $_.state -eq "Stopped"}|Remove-Job
とすると完了済みと中止したジョブを削除します。実行中のジョブは削除できませんが-forceパラメータを使って強制削除することは可能です。
ジョブの実行結果データを取得するにはReceive-Jobコマンドレットを用います。
Get-Job|Receive-Job
とすると完了済みのジョブのうち、結果を返却しているもの（HasMoreDataがTrueのジョブ）があればその結果を表示します。-keepパラメータをつければ結果データを保持しますが付けてない場合は参照後破棄します。
*-Job系のコマンドレットの多くはJobオブジェクトを返却するので、パイプラインでどんどん繋げていけます。
Get-Job|Wait-Job -timeout 10|Receive-Job
のように。
ジョブの基本的な使い方に関して詳しくはabout_jobsを参照してください。
イベントサブスクライブ
PowerShell 2.0では.NET Frameworkのオブジェクトのイベントをサブスクライブすることができます。すなわちイベントハンドラを記述することができます。このイベントサブスクライブ機能もジョブ機能を元に構築されています。
たとえばTimerオブジェクトのElapsedイベントをサブスクライブし、タイマーの実行間隔（ここでは1秒）ごとにtest.txtファイルに乱数を追記していくサンプルは次のようになります。
$timer=new-object System.Timers.Timer
$timer.Interval=1000
Register-ObjectEvent -EventName Elapsed -SourceIdentifier test -Action {get-random|add-content c:\users\daisuke\test.txt} -InputObject $timer
$timer.Enabled=$true
Register-ObjectEventの結果、新しくジョブが生成しそのJobオブジェクトが返却されます。このジョブは-EventNameパラメータで指定したイベントが発生するたび、-Actionパラメータで指定したスクリプトブロックを実行します。
なお、イベントサブスクライブを解除するには
Unregister-Event test
のように-SourceIdentifierパラメータで指定した値を指定してUnregister-Eventコマンドレットを実行することで可能です。サブスクライブを解除してもジョブ自体は削除されない（StateがStoppedになるだけ）ので、必要であればRemove-Jobで削除します。
なお.NETオブジェクトの他にPowerShellスクリプトのカスタムイベント（Register-EngineEvent）、WMIオブジェクトのイベント（Register-WmiEvent）をサブスクライブすることもできます。これらのコマンドレットも同様にイベント発生時の処理をジョブとして登録します。詳しくは各コマンドレットのヘルプを参照してください。
リモートコンピュータでのジョブ実行
最初に述べたとおりPowerShellのジョブ機能はリモートインフラストラクチャの上に構築されています。よってローカルのみならずリモートコンピュータに対してジョブを実行することができます。もちろんリモートコンピュータにもリモート構成されていることが条件です。
基本はInvoke-Commandコマンドレットを用い、
$job=Invoke-Command -ComputerName リモートコンピュータ名 {リモートで実行するコマンド、スクリプト} -asjob
となります。これで{}内の処理がリモートコンピュータ上のPowerShellインスタンスで実行されます。-asJobパラメータをつけることでジョブとして（ローカルPCから見て）非同期に処理できますが、-asJobパラメータを省略すると同期的に実行されます。この場合ジョブは作成されず、リモートでの処理が終了するまでローカル側は待機することになります。
リモートコンピュータに接続するための資格情報を別途入力する必要がある場合は-credentialパラメータを使用します。
Invoke-Command -ComputerName リモートコンピュータ名 {リモートで実行するコマンド、スクリプト} -asjob -credential ユーザー名
とするとパスワードを入力するダイアログが表示されます。なお、スクリプトで動かすときなどあらかじめ入力したパスワードを指定したい場合の方法は以前書きました。
同じコマンドを複数のリモートPCで同時実行することも可能で、その場合は-computerNameパラメータにリモートコンピュータ名の配列を指定します（「,」区切り）。この場合ローカルPCで見えるジョブとしては1つですが、そのジョブにリモートコンピュータの数だけ子ジョブ（ChildJobs）が作成されています。
このように子ジョブが複数ある場合にReceive-Jobするときは
$job|Receive-Job -location リモートコンピュータ名
あるいは
$job.ChildJobs
として表示される子ジョブの名前(Name)を調べ、
Receive-Job -name 子ジョブの名前
とすることでリモートコンピュータごとに結果を取得できます。
すべての結果をまとめて取得するなら
Receive-Job $job
とします。
$job|Receive-Jobはなぜか駄目なようです。
固定セッションを用いたリモーティング
同じリモートPCに対して何度もコマンドを実行させたい場合、毎回リモートコンピュータ名を指定してセッションを張るのは非効率的なので、リモートセッションを確立したあとその固定セッションを何度も使用する方法が用意されています。新しく固定セッションを確立するにはNew-PSSessionコマンドレットを用い、
$session=New-PSSession リモートコンピュータ名
とすると固定セッションが確立され、$session変数にそのセッションオブジェクトが格納されます。あとは
Invoke-Command $session {リモートで実行するコマンド、スクリプト} -asjob
とすればそのたびにそのセッションを用いてリモートでコマンドを実行できるようになります。
ここまでの説明はリモートコンピュータでしてきましたが、ローカルコンピュータに対して固定セッションを張ることも可能です。
さらに、Enter-PSSessionコマンドレットを用いると作成したセッションに入ってリモートコンピュータ上のPowerShellを対話実行することも可能です。
Enter-PSSession $session
とすると、プロンプトが
PS カレントディレクトリ>
から
[リモートコンピュータ名]: PS カレントディレクトリ>
に変化し、以降リモートのPowerShellをローカルPCから対話実行できます。
なおこの状態から抜けるにはexitもしくはExit-PSSessionと入力して実行します。
ジョブ実行できるそのほかのコマンドレット
これまで述べたコマンドレット以外にも、いくつかのコマンドレットはジョブ実行（ローカルorリモート）することができます。ジョブ実行するには-asJobパラメータを使用します。以下にv2の段階で-asJobパラメータが定義されているそのほかのコマンドレットを示します。
- Get-WmiObject
- Invoke-WmiMethod
- Remove-WmiObject
- Set-WmiInstance
- Test-Connection
- Restart-Computer
- Stop-Computer
これらのコマンドレットはコマンドレット自体にジョブ実行機能がついているので、単独で実行するだけならStart-JobやInvoke-Commandを用いる必要がありません。v2ではWMIを扱うコマンドレットにのみ-asJobパラメータが存在するようです（ここに挙げたコマンドレットはすべてWMIの機能を呼び出すもの）。なお、-asJobパラメータが使用できるコマンドレットの一覧を取得するのに、fsugiyamaさんの1日目の記事の問15のスクリプトを使用させていただきました。
おわりに
PowerShell Advent Calendar 2011二日目は、PowerShellのバックグラウンドジョブ機能概要についてまとめてみました。実はバックグランドジョブ機能のTipsを書こうと思ってその前ふりとして書き始めたのですが、これだけでかなりの量になってしまったので概要だけ一記事としてまとめることにしました。おそらくPSアドベントカレンダーに私はあと何回か登場することになりそうですので、Tips編はその際に書こうと思います。
さて、明日三日目は@jsakamotoさんのご登場ですね。よろしくお願いします！
そして参加者はまだまだ募集中ですよ！→PowerShell Advent Calendar 2011
Copyright © 2005-2016 Daisuke Mutaguchi All rights reserved
mailto: mutaguchi at roy.hi-ho.ne.jp
