トピック
about_Scripts
簡易説明
Windows PowerShell のスクリプトを作成および実行する方法について説明します。
詳細説明
スクリプトとは、1 つまたは複数の Windows PowerShell コマンドを含むプレーン テキスト ファイ
ルです。Windows PowerShell のスクリプトのファイル名拡張子は .ps1 です。
スクリプトを作成することで、後でコマンドを再入力する手間を省き、簡単に他のユーザーとコマンドを
共有できるようになります。最も有用なのは、スクリプトのパスとファイル名を入力するだけでコマンドを
実行できることです。スクリプトは、1 つのコマンドで構成される単純なものから、複雑で大規模な
プログラムまで、さまざまなものがあります。
スクリプトは、#Requires 特殊コメント、パラメーターの使用、Data セクションのサポート、
セキュリティを確保するためのデジタル署名など、さまざまな機能を備えています。スクリプト
やスクリプト内の任意の関数に対するヘルプ トピックを記述することもできます。
スクリプトの作成方法
スクリプトには、任意の有効な Windows PowerShell コマンドを含めることができます。つまり、単
独のコマンドに加えて、パイプライン、関数、制御構造 (If ステートメントや For ループなど) を
使用するコマンドを含めることができます。
スクリプトを作成するには、テキスト エディター (メモ帳など) またはスクリプト エディター
(Windows PowerShell Integrated Scripting Environment (ISE) など) を起動します。コマンド
を入力し、有効なファイル名と .ps1 ファイル名拡張子を付けたファイルに保存します。
次の例に、現在のシステム上で実行されているサービスの名前を取得してログ ファイルに保存する
単純なスクリプトを示します。ログ ファイルの名前は、現在の日付から作成されます。
$date = (get-date).dayofyear
get-service | out-file "$date.log"
このスクリプトを作成するには、テキスト エディターまたはスクリプト エディターを開き、これ
らのコマンドを入力して、ServiceLog.ps1 という名前のファイルに保存します。
スクリプトの実行方法
スクリプトを実行する前に、Windows PowerShell の既定の実行ポリシーを変更する必要がありま
す。既定の実行ポリシーである "Restricted" では、ローカル コンピューター上に作成したスク
リプトを含むすべてのスクリプトの実行が禁止されます。詳細については、
「about_Execution_Policies」を参照してください。
スクリプトを実行するには、スクリプト ファイルの完全な名前を含む完全なパスを入力します。
たとえば、C:\Scripts ディレクトリにある ServicesLog スクリプトを実行するには、次のように入力
します。
c:\scripts\ServicesLog.ps1
現在のディレクトリにあるスクリプトを実行するには、現在のディレクトリへのパスを入力するか、
または現在のディレクトリを表すドットに続けてバックスラッシュ (.\) を使用します。
たとえば、ローカル ディレクトリにある ServicesLog.ps1 スクリプトを実行するには、次のように
入力します。
.\ServicesLog.ps1
Windows PowerShell のセキュリティ機能により、Windows エクスプローラーでスクリプト アイ
コンをダブルクリックしても、スクリプトは実行されません。また、スクリプトが現在のディレ
クトリに存在する場合でも、入力したスクリプト名に完全なパスが含まれていなければ、スクリ
プトは実行されません。Windows PowerShell のコマンドおよびスクリプトの実行の詳細について
は、「about_Command_Precedence」を参照してください。
スクリプトのリモート実行
リモート コンピューター上でスクリプトを実行するには、Invoke-Command コマンドレットの
FilePath パラメーターを使用します。
FilePath パラメーターの値として、スクリプトのパスとファイル名を入力します。スクリプト
は、ローカル コンピューター上またはローカル コンピューターがアクセスできるディレクトリ
内に保存されている必要があります。
次のコマンドは、ServicesLog.ps1 スクリプトを Server01 リモート コンピューター上で実行します。
invoke-command -computername Server01 -filepath C:\scripts\servicesLog.ps1
スクリプトのパラメーター
パラメーターをスクリプト内で定義するには、Param ステートメントを使用します。Param ス
テートメントは、コメントおよび #Requires ステートメントを除き、スクリプト内で最初のス
テートメントである必要があります。
スクリプトのパラメーターは、関数のパラメーターと同様に機能します。パラメーター値は、
スクリプト内のすべてのコマンドで使用できます。パラメーター属性および名前付き引数を含む
関数パラメーターのすべての機能が、スクリプトでも有効です。
スクリプトを実行する場合は、スクリプト名に続けてパラメーターを入力します。
次の例は、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」を参照してください。
スクリプトのヘルプ
Get-Help コマンドレットは、スクリプト、コマンドレット、プロバイダー、および関数のヘルプ
を表示します。スクリプトのヘルプを表示するには、Get-Help に続けてスクリプトのパスとファ
イル名を入力します。スクリプトのパスが Path 環境変数に含まれている場合は、パスを省略できます。
たとえば、ServicesLog.ps1 スクリプトのヘルプを表示するには、次のように入力します。
get-help C:\admin\scripts\ServicesLog.ps1
次の 2 つの方法のいずれかを使用すると、スクリプトのヘルプを作成することができます。
-- スクリプトのコメントベースのヘルプ
コメントで特殊なキーワードを使用して、ヘルプ トピックを作成します。スクリプトのコメ
ントベースのヘルプを作成するには、スクリプト ファイルの先頭または末尾にコメントを配置
する必要があります。コメントベースのヘルプの詳細については、
「about_Comment_Based_Help」を参照してください。
-- スクリプトの XML ベースのヘルプ
通常コマンドレットに作成する種類と同様の XML ベースのヘルプ トピックを作成します。
ヘルプ トピックを複数の言語に翻訳する場合は、XML ベースのヘルプが必要です。
スクリプトと XML ベースのヘルプ トピックを関連付けるには、.ExternalHelp ヘルプ
コメント キーワードを使用します。ExternalHelp キーワードの詳細については、
「about_Comment_Based_Help」を参照してください。XML ベースのヘルプの詳細については、
MSDN (Microsoft Developer Network) ライブラリの「コマンドレット ヘルプの記述方法
(英語ページの可能性があります)」(https://go.microsoft.com/fwlink/?LinkID=123415) を
参照してください。
スクリプトのスコープとドット ソース
それぞれのスクリプトは、そのスクリプト独自のスコープ内で実行されます。スクリプト内で
作成された関数、変数、エイリアス、およびドライブは、スクリプト スコープにのみ存在しま
す。スクリプトの実行元のスコープでは、これらの項目や項目の値にアクセスすることはでき
ません。
異なるスコープでスクリプトを実行するには、Global や Local などのスコープを指定するか、
ドット ソースを使用してスクリプトを読み込みます。
ドット ソース機能を使用すると、スクリプト スコープではなく現在のスコープでスクリプトを
実行できます。ドット ソースによってスクリプトを実行すると、スクリプト内のコマンドは、
コマンド プロンプトに入力した場合と同じように実行されます。スクリプトによって作成される
関数、変数、エイリアス、およびドライブは、操作中のスコープで作成されます。スクリプトの
実行後は、作成された項目をセッション内で使用して項目の値にアクセスできます。
ドット ソースを使用してスクリプトを読み込むには、スクリプト パスの前にドット (.) と空白
を入力します。
次にその例を示します。
. C:\scripts\UtilityFunctions.ps1
- または -
. .\UtilityFunctions.ps1
UtilityFunctions スクリプトが実行された後、スクリプトによって作成された関数および変数が現在
のスコープに追加されます。
たとえば、UtilityFunctions.ps1 スクリプトは、New-Profile 関数と $ProfileName 変数を作成します。
#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
文字列 'new-profile' は、コマンドレット、関数、操作可能なプログラム、またはスク
リプト ファイルの名前として認識されません。文字列を確認し、再試行してください。
行:1 文字: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 の関連するリソースのセットで、1 つの単位として配布するこ
とができます。モジュールを使用することで、スクリプト、関数、その他のリソースを整理できま
す。また、モジュールを使用して、コードを他のユーザーに配布したり、信頼できるソースからコ
ードを取得したりすることもできます。
モジュールにはスクリプトを含めることができます。また、全部または大部分がスクリプトとその
サポート リソースから構成される、スクリプト モジュールを作成することもできます。スクリプ
ト モジュールは、ファイル名拡張子が .psm1 のスクリプトにすぎません。
モジュールの詳細については、「about_Modules」を参照してください。
その他のスクリプト機能
Windows PowerShell は、スクリプトで使用できる便利な機能を多数備えています。
#Requires
#Requires ステートメントを使用すると、指定されたモジュールやスナップインがない場合、
および指定されたバージョンの Windows PowerShell を使用できない場合に、スクリプトの
実行を禁止できます。詳細については、「about_Requires」を参照してください。
$MyInvocation
$MyInvocation 自動変数は、現在のスクリプトを含め、現在のコマンドに関する情報を格納し
ます。この変数とプロパティを使用して、実行中のスクリプトに関する情報を取得できます。
たとえば、$MyInvocation.MyCommand.Path 変数には、スクリプトのパスとファイル名が格納
されています。
Data セクション
Data キーワードを使用すると、データとスクリプト内のロジックとを切り離すことができます。
また、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_Scopes
about_Script_Blocks
about_Signing
Invoke-Command