about_Scripts
適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0
トピック
about_Scripts
概要
Windows PowerShell® でスクリプトを記述し、実行する方法について説明します。
詳細説明
スクリプトは、1 つまたは複数の Windows PowerShell コマンドが含まれているプレーン テキスト ファイルです。Windows PowerShell スクリプトのファイル名拡張子は .ps1 です。
スクリプトの実行は、コマンドレットの実行とよく似ています。スクリプトのパスとファイル名を入力し、パラメーターを使用してデータを渡し、オプションを設定します。スクリプトは、ローカル コンピューターで実行したり、別のコンピューターのリモート セッションで実行したりできます。
スクリプトを記述すると、後で使用するコマンドが保存されるため、他のユーザーと共有するのが容易になります。最も重要なのは、スクリプトのパスとファイル名を入力するだけで、コマンドを実行できることです。スクリプトは、ファイルにコマンドが 1 つだけある簡単なものにすることも、複雑なプログラムのように大規模なものにすることもできます。
スクリプトには、#Requires による特殊なコメント、パラメーターの使用、データ セクションのサポート、デジタル署名によるセキュリティなど、追加の機能があります。また、スクリプトおよびスクリプト内の任意の関数に関するヘルプ トピックを記述することもできます。
スクリプトを実行する方法
スクリプトを実行するには、既定の Windows PowerShell 実行ポリシーを変更する必要があります。既定の実行ポリシー "制限" を使用すると、ローカル コンピューターに記述したスクリプトを含め、すべてのスクリプトが実行されなくなります。詳細については、「about_Execution_Policies」を参照してください。
実行ポリシーはレジストリに保存されるため、これを各コンピューターで 1 回だけ変更する必要があります。
実行ポリシーを変更するには、次の手順に従います。
1. [管理者として実行] オプションを指定して、Windows PowerShell を起動します。
2. コマンド プロンプトで、次のように入力します。
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
セキュリティ機能として、スクリプトが現在のディレクトリにある場合でも、エクスプローラーでスクリプトのアイコンをダブルクリックしたときや、スクリプト名を完全パスなしで入力したときには、Windows PowerShell はスクリプトを実行しません。Windows PowerShell でのコマンドおよびスクリプトの実行の詳細については、「about_Command _Precedence」を参照してください。
PowerShell で実行
Windows PowerShell 3.0 以降では、エクスプローラー (または Windows の以前のバージョンでは Windows エクスプローラー) からスクリプトを実行できます。
"PowerShell で実行" 機能を使用するには、次のようにします。
エクスプローラー (または Windows エクスプローラー) で、スクリプト ファイル名を右クリックして [PowerShell で実行] を選択します。
"PowerShell で実行" 機能は、必須のパラメーターがなく、コマンド プロンプトに出力を返さないスクリプトを実行するために設計されています。
詳細については、「about_Run_With_PowerShell」を参照してください。
他のコンピューターでのスクリプトの実行
1 台以上のリモート コンピューターでスクリプトを実行するには、Invoke-Command コマンドレットの FilePath パラメーターを使用します。
FilePath パラメーターの値として、スクリプトのパスとファイル名を入力します。スクリプトは、ローカル コンピューター上か、またはローカル コンピューターがアクセスできるディレクトリ内に存在する必要があります。
次のコマンドは、Server01 と Server02 のリモート コンピューターで Get-ServiceLog.ps1 スクリプトを実行します。
Invoke-Command -ComputerName Server01, Server02 -FilePath C:\Scripts\Get-ServiceLog.ps1
スクリプトのヘルプの取得
Get-Help コマンドレットは、コマンドレットやその他の種類のコマンドに加え、スクリプトについてもヘルプ トピックを取得します。スクリプトのヘルプ トピックを取得するには、「Get-Help」と入力し、その後にスクリプトのパスとファイル名を続けます。スクリプトのパスが Path 環境変数にある場合は、パスを省略できます。
たとえば、ServicesLog.ps1 スクリプトのヘルプを取得するには、次のように入力します。
get-help C:\admin\scripts\ServicesLog.ps1
スクリプトを作成する方法
スクリプトには、単一のコマンドや、パイプライン、関数、および If ステートメントや For ループなどの制御構造を使用するコマンドなど、有効な Windows PowerShell コマンドを含めることができます。
スクリプトを記述するには、テキスト エディター (メモ帳など) やスクリプト エディター (Windows PowerShell Integrated Scripting Environment [ISE] など) を起動します。コマンドを入力し、有効なファイル名とファイル名拡張子 .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
Ping succeeded: Server01
Remote test failed: Server01
Param ステートメントおよび関数パラメーターの詳細については、「about_Functions」および「about_Functions_Advanced_Parameters」を参照してください。
スクリプトのヘルプの記述
スクリプトのヘルプ トピックを記述するには、次の 2 つの方法のいずれかを使用します。
-- スクリプトのコメント ベースのヘルプ
ヘルプ トピックを作成するには、コメントで特別なキーワードを使用します。スクリプトのコメント ベースのヘルプを作成するには、スクリプト ファイルの先頭または最後にコメントを配置する必要があります。コメント ベースのヘルプの詳細については、「about_Comment_Based_Help」を参照してください。
-- スクリプトの XML ベースのヘルプ
コマンドレット用に通常作成される種類など、XML ベースのヘルプ トピックを作成します。ヘルプ トピックを複数の言語に変換する場合には、XML ベースのヘルプが必要です。
スクリプトを XML ベースのヘルプ トピックに関連付けるには、ExternalHelp ヘルプ コメント キーワードを使用します。ExternalHelp キーワードの詳細については、「about_Comment_Based_Help」を参照してください。XML ベースのヘルプの詳細については、https://go.microsoft.com/fwlink/?LinkID=123415 で MSDN (Microsoft Developer Network) ライブラリの「コマンドレットのヘルプの記述方法」を参照してください。
スクリプトのスコープとドット ソース形式での読み込み
各スクリプトは、独自のスコープで実行されます。スクリプトで作成される関数、変数、エイリアス、およびドライブは、スクリプト スコープにのみ存在します。スクリプトが実行されるスコープ内のこれらの項目やその値にアクセスすることはできません。
別のスコープでスクリプトを実行するには、Global や Local などのスコープを指定するか、またはスクリプトをドット ソース形式で読み込みます。ここにセクション本体を挿入します。
ドット ソース形式での読み込み機能を使用すると、スクリプト スコープではなく、現在のスコープでスクリプトを実行できます。ドット ソース形式で読み込まれたスクリプトを実行すると、スクリプト内のコマンドがコマンド プロンプトに入力したかのように実行されます。スクリプトが作成する関数、変数、エイリアス、およびドライブは、現在作業しているスコープ内に作成されます。スクリプトの実行後、現在のセッションで、作成された項目を使用し、その値にアクセスできます。
スクリプトをドット ソース形式で読み込むには、スクリプト パスの前にドット (.) とスペースを 1 つずつ入力します。
たとえば、次のように入力します。
. C:\scripts\UtilityFunctions.ps1
- または -
. .\UtilityFunctions.ps1
UtilityFunctions スクリプトの実行後、スクリプトが作成する関数と変数が、現在のスコープに追加されます。
たとえば、UtilityFunctions.ps1 スクリプトは、New-Profile 関数と $ProfileName 変数を作成します。
#In UtilityFunctions.ps1
function New-Profile
{
Write-Host "Running New-Profile function"
$profileName = split-path $profile -leaf
if (test-path $profile)
{write-error "There is already a $profileName profile on this computer."}
else
{new-item -type file -path $profile -force }
}
独自のスクリプト スコープで UtilityFunctions.ps1 スクリプトを実行した場合、New-Profile 関数と $ProfileName 変数はスクリプトの実行中にのみ存在します。スクリプトの終了時に、次の例に示すように、関数と変数は削除されます。
C:\PS> .\UtilityFunctions.ps1
C:\PS> New-Profile
The term 'new-profile' is not recognized as a cmdlet, function, operable
program, or script file. Verify the term and try again.
At line:1 char:12
+ new-profile <<<<
+ CategoryInfo : ObjectNotFound: (new-profile:String) [],
+ FullyQualifiedErrorId : CommandNotFoundException
C:\PS> $profileName
C:\PS>
スクリプトをドット ソース形式で読み込んで実行した場合、スクリプトは現在のセッションの現在のスコープに New-Profile 関数と $ProfileName 変数を作成します。スクリプトの実行後、次の例に示すように、現在のセッションで New-Profile 関数を使用できます。
C:\PS> . .\UtilityFunctions.ps1
C:\PS> New-Profile
Directory: C:\Users\juneb\Documents\WindowsPowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 1/14/2009 3:08 PM 0 Microsoft.PowerShellISE_profile.ps1
C:\PS> $profileName
Microsoft.PowerShellISE_profile.ps1
スコープの詳細については、「about_Scopes」を参照してください。
モジュール内のスクリプト
モジュールは、単位として配布可能な一連の関連する Windows PowerShell リソースです。モジュールを使用すると、スクリプト、関数、およびその他のリソースを整理できます。また、自分のコードを他のユーザーに配布したり、信頼できるソースからコードを入手したりできます。
モジュールにスクリプトを含めたり、スクリプト モジュールを作成したりできます。スクリプト モジュールは、スクリプトとそのサポート リソースで全部またはほとんどが構成されているモジュールです。スクリプト モジュールは、.psm1 というファイル名拡張子を持つスクリプトにすぎません。
モジュールについての詳細については、「about_Modules」を参照してください。
その他のスクリプト機能
Windows PowerShell には、スクリプトで使用できる多くの便利な機能があります。
- #Requires
#Requires ステートメントを使用すると、指定されたモジュールまたはスナップインと、指定されたバージョンの Windows PowerShell がない場合には、スクリプトが実行されないようにすることができます。詳細については、「about_Requires」を参照してください。
- $PSCommandPath
実行されるスクリプトの完全パスと名前が含まれています。このパラメーターは、すべてのスクリプトで有効です。この自動変数は、Windows PowerShell 3.0 で導入されました。
- $PSScriptRoot
スクリプトの実行元となるディレクトリが含まれています。Windows PowerShell 2.0 では、この変数はスクリプト モジュール (.psm1) でのみ有効です。Windows PowerShell 3.0 以降では、すべてのスクリプトで有効です。
$MyInvocation
$MyInvocation 自動変数には、現在のスクリプトについて、開始または起動の方法などの情報が含まれています。この変数とそのプロパティを使用して、スクリプトの実行中にスクリプトに関する情報を取得できます。たとえば、$MyInvocation.MyCommand.Path 変数には、スクリプトのパスとファイル名が含まれています。$MyInvocation.Line には、すべてのパラメーターや値など、スクリプトを開始したコマンドが含まれています。Windows PowerShell 3.0 以降の $MyInvocation には、現在のスクリプトを呼び出したか、または起動したスクリプトに関する情報を提供する 2 つの新しいプロパティがあります。これらのプロパティの値は、起動元または呼び出し元がスクリプトである場合にのみ設定されます。
-- PSCommandPath には、現在のスクリプトを呼び出したか、または起動したスクリプトの完全パスと名前が含まれています。
-- PSScriptRoot には、現在のスクリプトを呼び出したか、または起動したスクリプトのディレクトリが含まれています。
現在のスクリプトに関する情報が含まれている $PSCommandPath 自動変数と $PSScriptRoot 自動変数とは異なり、$MyInvocation 変数の PSCommandPath プロパティと PSScriptRoot プロパティには、現在のスクリプトを呼び出したか、または起動したスクリプトに関する情報が含まれています。
- データ セクション
Data キーワードを使用すると、スクリプト内でデータをロジックから分離できます。データ セクションにより、ローカライズも容易になります。詳細については、「about_Data_Sections」および「about_Script_Localization」を参照してください。
- スクリプトへの署名
スクリプトにデジタル署名を追加できます。実行ポリシーによっては、デジタル署名を使用して、安全でないコマンドが含まれている可能性があるスクリプトの実行を制限できます。詳細については、「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