about_Scripts

簡単な説明

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

長い説明

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

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

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

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

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

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

既定の実行ポリシー である は、ローカル コンピューターに書き込むスクリプトを含め、すべての Restricted スクリプトを実行できません。 詳細については、「about_Execution_Policies」を参照してください。

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

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

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

Set-ExecutionPolicy AllSigned

または

Set-ExecutionPolicy RemoteSigned

変更はすぐに有効になります。

スクリプトを実行するには、スクリプトファイルの完全な名前と完全なパスを入力します。

たとえば、Get-ServiceLog.ps1 スクリプトを C:\Scripts ディレクトリで実行するには、次のように入力します。

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つまたは複数のリモートコンピューターでスクリプトを実行するには、コマンドレットの FilePath パラメーターを使用し Invoke-Command ます。

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

次のコマンドは、 Get-ServiceLog.ps1 Server01 と Server02 という名前のリモートコンピューター上でスクリプトを実行します。

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

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

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

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

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

$date = (get-date).dayofyear
get-service | out-file "$date.log"

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

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

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

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

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

次の例は Test-Remote.ps1 、ComputerName パラメーターを持 つスクリプトを示 しています。 どちらのスクリプト関数も 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 つの方法のいずれかを使用して記述できます。

  • スクリプトの Comment-Based ヘルプ

    コメントに特殊なキーワードを使用して、ヘルプトピックを作成します。 スクリプトのコメントベースのヘルプを作成するには、スクリプトファイルの先頭または末尾にコメントを配置する必要があります。 コメントベースのヘルプの詳細については、「 about_Comment_Based_Help」を参照してください。

  • スクリプトの XML-Based ヘルプ

    コマンドレットに対して通常作成される型など、XML ベースのヘルプトピックを作成します。 ヘルプトピックを複数の言語に翻訳する場合は、XML ベースのヘルプが必要です。

スクリプトを XML ベースのヘルプトピックに関連付けるには、を使用します。ExternalHelp ヘルプコメントキーワード。 ExternalHelp キーワードの詳細については、「 about_Comment_Based_Help」を参照してください。 XML ベースのヘルプの詳細については、「 How To Write Cmdlet help」を参照してください。

終了値を返す

既定では、スクリプトはスクリプトの終了時に終了状態を返しません。 exitスクリプトから終了コードを返すには、ステートメントを使用する必要があります。 既定では、 exit ステートメントはを返し 0 ます。 数値を指定すると、別の終了ステータスを返すことができます。 ゼロ以外の終了コードは、通常、エラーを通知します。

Windows では、との間に任意の数の数値を [int]::MinValue [int]::MaxValue 指定できます。

Unix で [byte]::MinValue は、(0) から (255) までの正の数値のみ [byte]::MaxValue が許可されます。 からまでの範囲の負の数値は、を -1 -255 追加することにより、自動的に正の数値に変換されます。 256. たとえば、 -2 はに変換され 254 ます。

PowerShell では、 ステートメント exit によって変数の値が設定 $LASTEXITCODE されます。 Windows コマンド シェル (cmd.exe) では、exit ステートメントによって環境変数の値が %ERRORLEVEL% 設定されます。

数値以外の引数、またはプラットフォーム固有の範囲外の引数は、 の値に変換されます 0

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

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

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

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

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

次に例を示します。

. C:\scripts\UtilityFunctions.ps1

or

. .\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。

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

モジュールは、一連の関連する PowerShell リソースであり、1つの単位として配布できます。 モジュールを使用して、スクリプト、関数、およびその他のリソースを整理することができます。 モジュールを使用して、コードを他のユーザーに配布したり、信頼されたソースからコードを取得したりすることもできます。

モジュールにスクリプトを含めることも、スクリプトモジュールを作成することもできます。スクリプトモジュールは、スクリプトとサポートリソースの全体または主に構成されているモジュールです。 スクリプトモジュールは、hbase-runner.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 より、 には、現在のスクリプトを呼び出したり呼び出したりしたスクリプトに関する情報を提供する 2 $MyInvocation つの新しいプロパティがあります。 これらのプロパティの値は、呼び出し元または呼び出し元がスクリプトの場合にのみ設定されます。

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

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

    現在のスクリプトに関する情報を含む および 自動変数とは異なり、変数の $PSCommandPath $PSScriptRoot PSCommandPath プロパティと PSScriptRoot プロパティには、現在のスクリプトを呼び出したスクリプトに関する情報が含 $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