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 つ以上のリモート コンピューターでスクリプトを実行するには、コマンドレットの 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 ステートメントを除き、スクリプトの最初のステートメントである必要があります。

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

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

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

  • スクリプトのコメント ベースのヘルプ

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

  • スクリプトの XML ベースのヘルプ

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

スクリプトを XML ベースのヘルプ トピックに関連付けるには、ExternalHelp ヘルプのコメント キーワード (keyword)。 ExternalHelp キーワード (keyword)の詳細については、about_Comment_Based_Helpを参照してください。 XML ベースのヘルプの詳細については、「コマンドレット ヘルプを記述する方法」を参照してください。

終了値を返す

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

Windows では、次の間 [int]::MinValue の任意の数が [int]::MaxValue 許可されます。

Unix では、(0) から [byte]::MinValue (255) [byte]::MaxValue までの正の数値のみが許可されます。 スルー-255の範囲内の負の-1数は、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 プロパティと PSScriptRoot プロパティには、現在の $MyInvocation スクリプトを呼び出したスクリプトに関する情報が含まれます。

  • データ セクション - キーワード (keyword)をData使用して、スクリプト内のロジックからデータを分離できます。 データ セクションを使用すると、ローカライズを容易にすることもできます。 詳細については、「about_Data_Sectionsとabout_Script_Internationalization」を参照してください。

  • スクリプト署名 - デジタル署名をスクリプトに追加できます。 実行ポリシーに応じて、デジタル署名を使用して、安全でないコマンドを含むことができるスクリプトの実行を制限できます。 詳細については、「about_Execution_Policiesとabout_Signing」を参照してください。

関連項目