about_Scripts

簡単な説明

PowerShell でスクリプトを実行および記述する方法について説明します。

詳細な説明

スクリプトは、1 つ以上の PowerShell コマンドを含むプレーン テキスト ファイルです。 PowerShell スクリプトには、 .ps1 ファイル拡張子があります。

スクリプトの実行は、コマンドレットの実行とよく似ています。 スクリプトのパスとファイル名を入力し、パラメーターを使用してデータを送信し、オプションを設定します。 スクリプトは、コンピューター上で実行することも、別のコンピューター上のリモート セッションで実行することもできます。

スクリプトを記述すると、後で使用するためにコマンドが保存され、他のユーザーと簡単に共有できるようになります。 最も重要なのは、スクリプト パスとファイル名を入力するだけでコマンドを実行できる点です。 スクリプトは、ファイル内の単一のコマンドと同じくらい簡単にすることも、複雑なプログラムと同じくらい広範囲にすることもできます。

スクリプトには、 #Requires 特別なコメント、パラメーターの使用、データ セクションのサポート、セキュリティのためのデジタル署名などの追加機能があります。 スクリプトやスクリプト内の任意の関数に関するヘルプ トピックを記述することもできます。

スクリプトを実行する方法

Windows でスクリプトを実行する前に、既定の PowerShell 実行ポリシーを変更する必要があります。 実行ポリシーは、Windows 以外のプラットフォームで実行されている PowerShell には適用されません。

既定の実行ポリシー Restrictedでは、ローカル コンピューターで記述したスクリプトを含め、すべてのスクリプトが実行されなくなります。 詳細については、「about_Execution_Policies」を参照してください。

実行ポリシーはレジストリに保存されるため、各コンピューターで 1 回だけ変更する必要があります。

実行ポリシーを変更するには、次の手順を使用します。

コマンド プロンプトで、次のコマンドを入力します。

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 パラメーターの値として、スクリプトのパスとファイル名を入力します。 スクリプトは、ローカル コンピューター上か、またはローカル コンピューターがアクセスできるディレクトリ内に存在する必要があります。

次のコマンドは、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

スクリプトを記述する方法

スクリプトには、1 つのコマンド、パイプラインを使用するコマンド、関数、If ステートメントや for ループなどの制御構造など、任意の有効な PowerShell コマンドを含めることができます。

スクリプトを記述するには、テキスト エディターで新しいファイルを開き、コマンドを入力して、ファイル拡張子が .ps1 の有効なファイル名を含むファイルに保存します。

次の例は、現在のシステムで実行されているサービスを取得し、ログ ファイルに保存する単純なスクリプトです。 ログ ファイル名は、現在の日付から作成されます。

$date = (Get-Date).DayOfYear
Get-Service | Out-File "$date.log"

このスクリプトを作成するには、テキスト エディターまたはスクリプト エディターを開き、これらのコマンドを入力して、 ServiceLog.ps1という名前のファイルに保存します。

スクリプト内のパラメーター

スクリプトでパラメーターを定義するには、param ステートメントを使用します。 param ステートメントは、コメントと#Requiresステートメントを除き、スクリプトの最初のステートメントである必要があります。

スクリプト パラメーターは、関数パラメーターと同様に機能します。 パラメーター値は、スクリプト内のすべてのコマンドで使用できます。 Parameter 属性とその名前付き引数を含む関数パラメーターのすべての機能は、スクリプトでも有効です。

スクリプトを実行する場合、スクリプト ユーザーはスクリプト名の後にパラメーターを入力します。

次の例は、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 ヘルプ コメント キーワードを使用します。 詳細については、以下を参照してください。

• 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の値に変換されます。

スクリプト スコープとドット ソーシング

各スクリプトは、独自のスコープで実行されます。 スクリプトで作成される関数、変数、エイリアス、およびドライブは、スクリプト スコープにのみ存在します。 スクリプトを実行するスコープ内のこれらの項目またはその値にアクセスすることはできません。

別のスコープでスクリプトを実行するには、グローバルやローカルなどのスコープを指定するか、スクリプトをドット ソースにすることができます。

ドット ソーシング機能を使用すると、スクリプト スコープではなく、現在のスコープでスクリプトを実行できます。 ドット ソースのスクリプトを実行すると、スクリプト内のコマンドは、コマンド プロンプトで入力したかのように実行されます。 スクリプトによって作成される関数、変数、エイリアス、およびドライブは、作業中のスコープに作成されます。 スクリプトの実行後、作成された項目を使用して、セッション内の値にアクセスできます。

スクリプトをドット ソースにするには、スクリプト パスの前にドット (.) とスペースを入力します。

次に例を示します。

. C:\scripts\UtilityFunctions.ps1

または

. .\UtilityFunctions.ps1

UtilityFunctions.ps1 スクリプトを実行すると、スクリプトによって作成される関数と変数が現在のスコープに追加されます。

たとえば、 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 "Profile $profileName already exists 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」を参照してください。

モジュール内のスクリプト

モジュールは、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.行には、スクリプトを開始したコマンド (すべてのパラメーターと値を含む) が含まれます。

  PowerShell 3.0 以降、 $MyInvocation には、現在のスクリプトを呼び出すか呼び出したスクリプトに関する情報を提供する 2 つの新しいプロパティがあります。 これらのプロパティの値は、呼び出し元または呼び出し元がスクリプトである場合にのみ設定されます。

  • PSCommandPath には、現在のスクリプトを呼び出した、または呼び出したスクリプトの完全なパスと名前が含まれています。

  • PSScriptRoot には、現在のスクリプトを呼び出した、または呼び出したスクリプトのディレクトリが含まれています。

  現在のスクリプトに関する情報を含む$PSCommandPathおよび$PSScriptRoot自動変数とは異なり、変数の PSCommandPath および $MyInvocation プロパティには、現在のスクリプトを呼び出したスクリプトに関する情報が含まれます。

• データ セクション - 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