about_Scripts

簡短描述

描述如何在PowerShell中執行和撰寫腳本。

詳細描述

腳本是包含一或多個 PowerShell 命令的純文字檔案。 PowerShell 腳本具有 .ps1 擴展名。

執行腳本非常像是執行 Cmdlet。 您可以輸入文稿的路徑和檔名，並使用參數來提交數據和設定選項。 您可以在您的電腦或不同電腦上的遠端工作階段中執行文稿。

撰寫文本會儲存命令以供日後使用，並可讓您輕鬆地與其他人共用。 最重要的是，它可讓您直接輸入腳本路徑和檔名來執行命令。 腳本可以像檔案中的單一命令一樣簡單，也可以像複雜程序一樣廣泛。

腳本具有其他功能，例如 #Requires 特殊批注、參數的使用、數據區段的支援，以及安全性的數字簽名。 您也可以針對文稿和文稿中的任何函式撰寫說明主題。

如何執行腳本

您必須先變更預設的 PowerShell 執行原則，才能在 Windows 上執行腳本。 執行原則不適用於在非 Windows 平台上執行的 PowerShell。

默認執行原則 Restricted會防止所有腳本執行，包括您在本機計算機上撰寫的腳本。 如需詳細資訊，請參閱 about_Execution_Policies。

執行原則會儲存在登錄中，因此您只需要在每部計算機上變更一次。

若要變更執行原則，請使用下列程式。

在命令提示字元中，輸入：

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。

在其他電腦上執行腳本

若要在一或多部遠端電腦上執行腳本，請使用 Cmdlet 的 Invoke-Command FilePath 參數。

輸入文本的路徑和檔名做為 FilePath 參數的值。 腳本必須位於本機電腦或本機計算機可以存取的目錄中。

下列命令會在 Get-ServiceLog.ps1 名為 Server01 和 Server02 的遠端電腦上執行腳本。

Invoke-Command -ComputerName Server01,Server02 -FilePath `
  C:\Scripts\Get-ServiceLog.ps1

取得腳本的說明

Get-Help Cmdlet 會取得腳本的說明主題，以及 Cmdlet 和其他類型的命令。 若要取得文稿的說明主題，請輸入 Get-Help 後面接著腳本的路徑和檔名。 如果文稿路徑位於環境變數 Path 中，您可以省略路徑。

例如，若要取得 ServicesLog.ps1 腳本的說明，請輸入：

get-help C:\admin\scripts\ServicesLog.ps1

如何撰寫腳本

腳本可以包含任何有效的 PowerShell 命令，包括單一命令、使用管線、函式及控制結構的命令，例如 If 語句和 For 迴圈。

若要撰寫文本，請在文本編輯器中開啟新的檔案、輸入命令，然後將命令儲存在擴展名為有效檔名的 .ps1 檔案中。

下列範例是簡單的腳本，可取得在目前系統上執行的服務，並將其儲存至記錄檔。 記錄檔檔名是從目前的日期建立。

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

若要建立此腳本，請開啟文本編輯器或腳本編輯器、輸入這些命令，然後將這些命令儲存在名為 ServiceLog.ps1的檔案中。

腳本中的參數

若要在腳本中定義參數，請使用 Param 語句。 語句 Param 必須是腳本中的第一個語句，但批註和任何 #Require 語句除外。

腳本參數的運作就像函式參數一樣。 參數值可供腳本中的所有命令使用。 函式參數的所有功能，包括Parameter屬性及其具名自變數，在腳本中也是有效的。

執行文稿時，腳本使用者會在腳本名稱後面輸入參數。

下列範例顯示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。

撰寫腳本的說明

您可以使用下列兩種方法之一，為腳稿撰寫說明主題：

• 腳本的批註型說明

  在批注中使用特殊關鍵詞建立說明主題。 若要建立腳本的批註型說明，批註必須放在腳本檔案的開頭或結尾。 如需批注型說明的詳細資訊，請參閱 about_Comment_Based_Help。

• 腳本的 XML 型說明

  建立 XML 型說明主題，例如通常針對 Cmdlet 建立的類型。 如果您要將說明主題翻譯成多種語言，則需要以 XML 為基礎的說明。

若要將文稿與 XML 型說明主題產生關聯，請使用 。ExternalHelp 說明批注關鍵詞。 如需 ExternalHelp 關鍵詞的詳細資訊，請參閱 about_Comment_Based_Help。 如需 XML 型說明的詳細資訊，請參閱 如何撰寫 Cmdlet 說明。

傳回結束值

根據預設，腳本在腳本結束時不會傳回結束狀態。 您必須使用 exit 語句，從腳本傳回結束代碼。 根據預設， exit 語句會傳 0回 。 您可以提供數值來傳回不同的結束狀態。 非零結束代碼通常表示失敗。

在 Windows 上，允許和 [int]::MaxValue 之間的[int]::MinValue任何數位。

在 Unix 上，只允許介於 （0） 和 [byte]::MaxValue （255） 之間的[byte]::MinValue正數。 透過範圍-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。

模組中的腳本

模組是一組相關的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.Line 包含啟動文稿的命令，包括所有參數和值。

  從 PowerShell 3.0 開始，有兩個新的屬性， $MyInvocation 提供呼叫或叫用目前腳本之腳本的相關信息。 只有在叫用者或呼叫端是腳本時，才會填入這些屬性的值。

  • PSCommandPath 包含呼叫或叫用目前腳本之腳本的完整路徑和名稱。

  • PSScriptRoot 包含呼叫或叫用目前腳本的腳本目錄。

  與 包含目前腳本相關信息的 $PSCommandPath 和 $PSScriptRoot 自動變數不同，變數的 $MyInvocation PSCommandPath 和 PSScriptRoot 屬性包含呼叫目前腳本之腳本的相關信息。

• 數據區段 - 您可以使用 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