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-CommandFilePath 參數。

輸入文本的路徑和檔名作為 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。

撰寫腳本的說明

您可以使用下列兩種方法之一來撰寫文稿的說明主題：

• 腳本的 Comment-Based 說明

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

• 腳本的 XML-Based 說明

  Create 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.ps1New-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 自動變數不同，變數的 $MyInvocationPSCommandPath 和 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