ja-JP/about_Scripts.help.txt
|
TOPIC about_Scripts 簡単な説明 PowerShell でスクリプトを実行および記述する方法を説明します。 詳細な説明 スクリプトは、1 つ以上の PowerShell コマンドを含むプレーンテキスト ファイルです。PowerShell スクリプトのファイル拡張子は .ps1 です。 スクリプトの実行は、コマンドレットの実行とよく似ています。スクリプトの パスとファイル名を入力し、パラメーターを使ってデータを渡したりオプションを 設定したりします。スクリプトは自分のコンピューターで実行することも、別の コンピューターのリモートセッションで実行することもできます。 スクリプトを記述すると、後で使うためにコマンドを保存でき、他の人と簡単に 共有できます。最も重要なのは、スクリプトのパスとファイル名を入力するだけで コマンドを実行できる点です。スクリプトは、ファイル内の 1 つのコマンドのように 単純なものから、複雑なプログラムのように大規模なものまであります。 スクリプトには、#Requires 特殊コメント、パラメーターの使用、データセクションの サポート、セキュリティのためのデジタル署名などの追加機能があります。スクリプト およびスクリプト内の関数のためのヘルプトピックを記述することもできます。 スクリプトの実行方法 Windows でスクリプトを実行するには、まず既定の PowerShell 実行ポリシーを 変更する必要があります。実行ポリシーは、Windows 以外のプラットフォームで 動作する PowerShell には適用されません。 既定の実行ポリシー Restricted は、ローカルコンピューターで記述した スクリプトを含め、すべてのスクリプトの実行を禁止します。詳しくは about_Execution_Policies を参照してください。 実行ポリシーはレジストリに保存されるため、各コンピューターで一度だけ変更 すればかまいません。 実行ポリシーを変更するには、コマンドプロンプトで次のように入力します。 Set-ExecutionPolicy AllSigned または Set-ExecutionPolicy RemoteSigned 変更は直ちに有効になります。 スクリプトを実行するには、スクリプトファイルの完全な名前と完全なパスを 入力します。 たとえば C:\Scripts ディレクトリにある Get-ServiceLog.ps1 スクリプトを 実行するには、次のように入力します。 C:\Scripts\Get-ServiceLog.ps1 現在のディレクトリでスクリプトを実行するには、現在のディレクトリへのパスを 入力するか、現在のディレクトリを表すドットの後にパス区切りの円記号 (.\) を 付けて入力します。 たとえばローカルディレクトリの ServicesLog.ps1 スクリプトを実行するには、 次のように入力します。 .\Get-ServiceLog.ps1 スクリプトにパラメーターがある場合は、スクリプトのファイル名の後にパラメーター とパラメーター値を入力します。 たとえば次のコマンドは、Get-ServiceLog スクリプトの ServiceName パラメーター を使って、WinRM サービスのアクティビティログを要求します。 .\Get-ServiceLog.ps1 -ServiceName WinRM セキュリティ機能として、エクスプローラーでスクリプトアイコンをダブルクリック したときや、完全なパスなしでスクリプト名を入力したときは、スクリプトが現在の ディレクトリにあっても PowerShell はスクリプトを実行しません。PowerShell での コマンドとスクリプトの実行について詳しくは、about_Command_Precedence を 参照してください。 PowerShell で実行 PowerShell 3.0 以降では、エクスプローラーからスクリプトを実行できます。 「PowerShell で実行」機能を使うには、エクスプローラーを起動し、スクリプトの ファイル名を右クリックして「PowerShell で実行」を選択します。 「PowerShell で実行」機能は、必須パラメーターを持たず、コマンドプロンプトに 出力を返さないスクリプトを実行するために設計されています。 詳しくは about_Run_With_PowerShell を参照してください。 他のコンピューターでのスクリプトの実行 1 台以上のリモートコンピューターでスクリプトを実行するには、Invoke-Command コマンドレットの FilePath パラメーターを使用します。 FilePath パラメーターの値として、スクリプトのパスとファイル名を入力します。 スクリプトはローカルコンピューター、またはローカルコンピューターがアクセス できるディレクトリに存在する必要があります。 次のコマンドは、Server01 と Server02 という名前のリモートコンピューターで Get-ServiceLog.ps1 スクリプトを実行します。 $invokeCommandSplat = @{ ComputerName = 'Server01', 'Server02' FilePath = 'C:\Scripts\Get-ServiceLog.ps1' } Invoke-Command @invokeCommandSplat スクリプトのヘルプを取得する Get-Help コマンドレットは、コマンドレットやその他の種類のコマンドと同様に、 スクリプトのヘルプトピックも取得します。スクリプトのヘルプトピックを取得 するには、Get-Help の後にスクリプトのパスとファイル名を入力します。スクリプト のパスが PATH 環境変数にある場合は、パスを省略できます。 たとえば ServicesLog.ps1 スクリプトのヘルプを取得するには、次のように 入力します。 Get-Help C:\admin\scripts\ServicesLog.ps1 スクリプトの記述方法 スクリプトには、単一のコマンド、パイプラインを使うコマンド、関数、および if ステートメントや for ループなどの制御構造を含め、有効な PowerShell コマンドを記述できます。 スクリプトを記述するには、テキストエディターで新しいファイルを開き、コマンドを 入力し、拡張子 .ps1 を持つ有効なファイル名で保存します。 次の例は、現在のシステムで実行中のサービスを取得してログファイルに保存する 単純なスクリプトです。ログのファイル名は現在の日付から作成されます。 $date = (Get-Date).DayOfYear Get-Service | Out-File "$date.log" このスクリプトを作成するには、テキストエディターまたはスクリプトエディターを 開き、これらのコマンドを入力して、ServiceLog.ps1 という名前のファイルに 保存します。 スクリプト内のパラメーター スクリプトでパラメーターを定義するには、param ステートメントを使います。 param ステートメントは、コメントと #Requires ステートメントを除き、スクリプト の最初のステートメントでなければなりません。 スクリプトパラメーターは関数パラメーターと同じように機能します。パラメーター値 はスクリプト内のすべてのコマンドで利用できます。Parameter 属性とその名前付き 引数を含む、関数パラメーターのすべての機能がスクリプトでも有効です。 スクリプトを実行するとき、ユーザーはスクリプト名の後にパラメーターを入力 します。 次の例は、ComputerName パラメーターを持つ Test-Remote.ps1 スクリプトを 示します。どちらのスクリプト関数も ComputerName パラメーター値にアクセス できます。 param ($ComputerName = $(throw "ComputerName parameter is required.")) function CanPing { $Error.Clear() $tmp = Test-Connection $ComputerName -ErrorAction SilentlyContinue if (!$?) {Write-Host "Ping failed: $ComputerName."; return $false} else {Write-Host "Ping succeeded: $ComputerName"; return $true} } function CanRemote { $s = New-PSSession $ComputerName -ErrorAction SilentlyContinue if ($s -is [System.Management.Automation.Runspaces.PSSession]) {Write-Host "Remote test succeeded: $ComputerName."} else {Write-Host "Remote test failed: $ComputerName."} } if (CanPing $ComputerName) {CanRemote $ComputerName} このスクリプトを実行するには、スクリプト名の後にパラメーター名を入力します。 C:\PS> .\test-remote.ps1 -ComputerName Server01 param ステートメントと関数パラメーターについて詳しくは、about_Functions と about_Functions_Advanced_Parameters を参照してください。 スクリプトのヘルプの記述 次の 2 つの方法のいずれかで、スクリプトのヘルプトピックを記述できます。 - スクリプトのコメントベースヘルプ コメント内の特殊なキーワードを使ってヘルプトピックを作成します。スクリプト のコメントベースヘルプを作成するには、コメントをスクリプトファイルの先頭 または末尾に配置する必要があります。詳しくは about_Comment_Based_Help を 参照してください。 - スクリプトの XML ベースヘルプ コマンドレット向けに通常作成されるような、XML ベースのヘルプトピックを 作成します。ヘルプトピックを複数の言語に翻訳する場合は、XML ベースヘルプが 必要です。 スクリプトを XML ベースヘルプトピックに関連付けるには、.EXTERNALHELP ヘルプコメントキーワードを使います。詳しくは about_Comment_Based_Help を 参照してください。 終了値を返す 既定では、スクリプトは終了時に終了ステータスを返しません。スクリプトから 終了コードを返すには、exit ステートメントを使う必要があります。既定では exit ステートメントは 0 を返します。数値を指定して別の終了ステータスを 返せます。通常、0 以外の終了コードは失敗を示します。 Windows では、[int]::MinValue から [int]::MaxValue までの任意の数値が 許可されます。 Unix では、[byte]::MinValue (0) から [byte]::MaxValue (255) までの正の数値 だけが許可されます。-1 から -255 の範囲の負の数値は、256 を加えることで 自動的に正の数値に変換されます。たとえば -2 は 254 に変換されます。 PowerShell では、exit ステートメントは $LASTEXITCODE 変数の値を設定します。 Windows コマンドシェル (cmd.exe) では、exit ステートメントは %ERRORLEVEL% 環境変数の値を設定します。 数値以外、またはプラットフォーム固有の範囲外の引数は、値 0 に変換されます。 スクリプトのスコープとドットソース 各スクリプトはそれぞれのスコープで実行されます。スクリプト内で作成された 関数、変数、エイリアス、ドライブは、スクリプトスコープ内だけに存在します。 スクリプトを実行したスコープでは、これらの項目やその値にアクセスできません。 スクリプトを別のスコープで実行するには、Global や Local などのスコープを 指定するか、スクリプトをドットソースします。 ドットソース機能を使うと、スクリプトスコープではなく現在のスコープで スクリプトを実行できます。ドットソースされたスクリプトを実行すると、 スクリプト内のコマンドはコマンドプロンプトで入力した場合と同じように実行 されます。スクリプトが作成する関数、変数、エイリアス、ドライブは、作業中の スコープに作成されます。スクリプトの実行後、作成された項目を使用したり、 その値にアクセスしたりできます。 スクリプトをドットソースするには、スクリプトパスの前にドット (.) と空白を 入力します。 例: . C:\scripts\UtilityFunctions.ps1 または . .\UtilityFunctions.ps1 UtilityFunctions.ps1 スクリプトの実行後、スクリプトが作成する関数と変数が 現在のスコープに追加されます。 スコープについて詳しくは、about_Scopes を参照してください。 モジュール内のスクリプト モジュールは、1 つの単位として配布できる関連する PowerShell リソースの 集合です。モジュールを使ってスクリプト、関数、その他のリソースを整理できます。 また、コードを他の人に配布したり、信頼できるソースからコードを取得したりする のにも使えます。 モジュールにスクリプトを含めることも、スクリプトモジュール (全体または主に スクリプトとサポートリソースで構成されるモジュール) を作成することもできます。 スクリプトモジュールは、拡張子 .psm1 を持つスクリプトに過ぎません。 モジュールについて詳しくは、about_Modules を参照してください。 その他のスクリプト機能 PowerShell には、スクリプトで使える便利な機能が多数あります。 - #Requires - #Requires ステートメントを使うと、指定したモジュールや スナップイン、指定したバージョンの PowerShell がない状態でスクリプトが 実行されるのを防げます。詳しくは about_Requires を参照してください。 - $PSCommandPath - 実行中のスクリプトの完全なパスと名前を含みます。すべての スクリプトで有効です。PowerShell 3.0 で導入されました。 - $PSScriptRoot - スクリプトが実行されているディレクトリを含みます。 PowerShell 2.0 ではスクリプトモジュール (.psm1) でのみ有効でした。 PowerShell 3.0 以降はすべてのスクリプトで有効です。 - $MyInvocation - $MyInvocation 自動変数は、開始方法 (呼び出し方) を含む、 現在のスクリプトに関する情報を含みます。この変数とそのプロパティを使って、 実行中のスクリプトに関する情報を取得できます。たとえば $MyInvocation.MyCommand.Path 変数にはスクリプトのパスとファイル名が、 $MyInvocation.Line には開始時のコマンド (すべてのパラメーターと値を含む) が含まれます。 - データセクション - Data キーワードを使うと、スクリプト内のデータとロジックを 分離できます。データセクションはローカライズも容易にします。詳しくは about_Data_Sections と about_Script_Internationalization を参照してください。 - スクリプト署名 - スクリプトにデジタル署名を追加できます。実行ポリシーに 応じて、デジタル署名を使って安全でないコマンドを含む可能性のあるスクリプト の実行を制限できます。詳しくは about_Execution_Policies と about_Signing を 参照してください。 関連項目 about_Command_Precedence about_Comment_Based_Help about_Execution_Policies about_Functions about_Modules about_Profiles about_Requires about_Run_With_PowerShell about_Scopes about_Script_Blocks about_Signing Invoke-Command ---- 原文: PowerShell-Docs (CC BY 4.0) の翻訳 / PSHelpJaJP |