主題 about_Scripts 簡短描述 描述如何在 Windows PowerShell 中撰寫和執行指令碼。 完整描述 指令碼是內含一個或多個 Windows PowerShell 命令的純文字檔。Windows PowerShell 指令碼的副檔名是 .ps1。 撰寫指令碼可儲存命令供日後使用,也能讓您輕鬆地與其他人共用。最重要的是,您 只需要輸入指令碼路徑和檔名就可以執行命令。指令碼可以很簡單如檔案中的單一命 令,也可以是複雜完整的程式。 指令碼還有其他功能,例如 #Requires 特殊註解、使用參數、支援資料區段,以及 安全性數位簽章等。您也可以撰寫指令碼的說明主題,以及指令碼中任何函數的說明 主題。 如何撰寫指令碼 指令碼可以包含任何有效的 Windows PowerShell 命令,包括單一命令、使用管線的 命令、函數以及控制結構,例如 If 陳述式和 For 迴圈。 若要撰寫指令碼,請啟動文字編輯器 (例如「記事本」),或指令碼編輯器 (例如 Windows PowerShell 整合式指令碼環境 (ISE))。請輸入命令,並將這些命令儲存在 檔名有效且副檔名為 .ps1 的檔案中。 下列範例是一個簡單的指令碼,它會取得目前系統所執行的服務,並將這些服務儲存 到記錄檔。記錄檔名稱是從目前的日期開始建立。 $date = (get-date).dayofyear get-service | out-file "$date.log" 若要建立此指令碼,請開啟文字編輯器或指令碼編輯器,輸入這些命令,然後將它們 儲存在名為 "ServiceLog.ps1" 的檔案中。 如何執行指令碼 您必須先變更預設的 Windows PowerShell 執行原則才能執行指令碼。預設執行原則 是 "Restricted",表示所有指令碼都無法執行,包括您在本機電腦撰寫的指令碼。 如需詳細資訊,請參閱 about_Execution_Policies。 若要執行指令碼,請輸入指令檔的完整名稱和完整路徑。 例如,若要執行 C:\Scripts 目錄中的 ServicesLog 指令碼,請輸入: c:\scripts\ServicesLog.ps1 若要執行目前目錄中的指令碼,請輸入目前目錄的路徑,或是使用點來代表目前的目 錄,後面再加上路徑反斜線 (.\)。 例如,若要執行本機目錄中的 ServicesLog.ps1 指令碼,請輸入: .\ServicesLog.ps1 當您按兩下 Windows 檔案總管中的指令碼圖示,或是輸入不含完整路徑的指令碼名 稱時,即使指令碼位於目前的目錄,Windows PowerShell 也不會執行指令碼,這是 一項安全性功能。如需在 Windows PowerShell 中執行命令和指令碼的詳細資訊, 請參閱 about_Command_Precedence。 從遠端執行指令碼 若要在遠端電腦執行指令碼,請使用 Invoke-Command Cmdlet 的 FilePath 參數。 請輸入指令碼的路徑和檔名,做為 Filepath 參數的值。此指令碼必須存在於本機電 腦或本機電腦可存取的目錄中。 下列命令會在 Server01 遠端電腦執行 ServicesLog.ps1 指令碼。 invoke-command -computername Server01 -filepath C:\scripts\servicesLog.ps1 指令碼中的參數 若要在指令碼中定義參數,請使用 Param 陳述式。除了註解和任何 #Requires 陳述 式以外,Param 陳述式必須是指令碼中的第一個陳述式。 指令碼參數的功能與函數參數類似。參數值可供指令碼中的所有命令使用。函數參數 (包括 Parameter 屬性及其具名引數) 的所有功能在指令碼中也都有效。 執行指令碼時,指令碼使用者可在指令碼名稱後面輸入參數。 下列範例會示範具有 ComputerName 參數的 Test-Remote.ps1 指令碼。以下兩個指 令碼函數都可以存取 ComputerName 參數值。 param ($ComputerName = $(throw "需要 ComputerName 參數。")) function CanPing { $error.clear() $tmp = test-connection $computername -erroraction SilentlyContinue if (!$?) {write-host "Ping 失敗: $ComputerName。"; return $false} else {write-host "Ping 成功: $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 "遠端測試失敗: $ComputerName。"} } if (CanPing $computername) {CanRemote $computername} 若要執行此指令碼,請在指令碼名稱後面輸入參數名稱。例如: C:\PS> .\test-remote.ps1 -computername Server01 Ping 成功: Server01 遠端測試失敗: Server01 如需 Param 陳述式與函數參數的詳細資訊,請參閱 about_Functions 和 about_Functions_Advanced_Parameters。 指令碼的說明 Get-Help Cmdlet 會取得指令碼以及 Cmdlet、提供者和函數的說明。若要取得指令 碼的說明,請輸入 Get-Help 以及指令碼的路徑和檔名。如果指令碼路徑是在 Path 環境變數中,您就可以省略路徑。 例如,若要取得 ServicesLog.ps1 指令碼的說明,請輸入: get-help C:\admin\scripts\ServicesLog.ps1 您可以使用下列其中一種方法來撰寫指令碼的說明: -- 以註解為基礎的指令碼說明 您可以在註解中使用特殊的關鍵字來建立說明主題。若要建立以註解為基礎的指 令碼說明,註解必須放在指令檔的開頭或結尾處。如需以註解為基礎之說明的詳 細資訊,請參閱 about_Comment_Based_Help。 -- 以 XML 為基礎的指令碼說明 您可以建立以 XML 為基礎的說明主題,例如通常會為 Cmdlet 所建立的說明類 型。如果您要將說明主題翻譯成多種語言,就必須使用以 XML 為基礎的說明。 若要讓指令碼與以 XML 為基礎的說明主題產生關聯,請使用 .ExternalHelp 說 明註解關鍵字。如需 ExternalHelp 關鍵字的詳細資訊,請參閱 about_Comment_Based_Help。如需有關以 XML 為基礎之說明的詳細資訊,請參閱 MSDN (Microsoft Developer Network) 文件庫中的<如何撰寫 Cmdlet 說明> (英文),網址為:https://go.microsoft.com/fwlink/?LinkID=123415。 指令碼範圍和 DOT SOURCING 每個指令碼都是在其個別的範圍內執行。在指令碼中建立的函數、變數、別名和磁碟 機都只存在指令碼範圍內,而且您不能在指令碼執行的範圍內存取這些項目或其值。 若要在不同的範圍中執行指令碼,您可以指定範圍 (例如「全域」或「本機」),或是 在指令碼前加點。 dot sourcing 功能可以讓您在目前的範圍 (而不是在指令碼範圍) 中執行指令碼。當 您執行指令碼前加點的指令碼時,指令碼中命令執行的方式就像在命令提示字元輸入 命令一樣。指令碼建立函數、變數、別名和磁碟機時,都會在您所使用的範圍內建立。 指令碼執行完成之後,您可以在自己的工作階段中使用其建立的項目並存取這些項目 的值。 若要在指令碼前加點,請在指令碼路徑前面輸入點 (.) 和空格。 例如: . C:\scripts\UtilityFunctions.ps1 - 或 - . .\UtilityFunctions.ps1 UtilityFunctions 指令碼執行完成之後,所建立的函數和變數便會新增到目前的範 圍中。 例如,UtilityFunctions.ps1 指令碼會建立 New-Profile 函數和 $ProfileName 變 數。 #在 UtilityFunctions.ps1 中 function New-Profile { Write-Host "正在執行 New-Profile 函數" $profileName = split-path $profile -leaf if (test-path $profile) {write-error "此電腦已有 $profileName 設定檔。"} else {new-item -type file -path $profile -force } } 如果您在 UtilityFunctions.ps1 指令碼本身的範圍內執行此 UtilityFunctions.ps1 指令碼,New-Profile 函數和 $ProfileName 變數只於指令碼執行期間存在。如下列 範例所示,當指令碼結束時,便會移除此函數和變數。 C:\PS> .\UtilityFunctions.ps1 C:\PS> New-Profile 'new-profile' 詞彙無法辨識是否為 Cmdlet、函數、可執行程式或指令檔。請確 認該詞彙,然後再試一次。 位於第 1 行,第 12 個字元 + new-profile <<<< + CategoryInfo<ch='32' Tm='10'>: 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。 模組中的指令碼 模組是一組相關、可以當做一個單位一起散發的 Windows PowerShell 資源。您可以 使用模組來組織指令碼、函數和其他資源。您也可以使用模組將程式碼散發給其他 人,以及從信任的來源取得程式碼。 您可以將指令碼包含在模組中,或是建立指令碼模組,也就是完全或主要是由指令碼 與輔助資源所組成的模組。指令碼模組只是副檔名為 .psm1 的指令碼。 如需模組的詳細資訊,請參閱 about_Modules。 其他指令碼功能 Windows PowerShell 具有許多實用的功能,可供您在指令碼中使用。 #Requires 您可以使用 #Requires 陳述式,要求必須有指定的模組或嵌入式管理單元以及 指定的 Windows PowerShell 版本時,才能執行指令碼。如需詳細資訊, 請參閱 about_Requires。 $MyInvocation $MyInvocation 自動變數包含目前命令 (包括目前的指令碼) 的相關資訊。您可 以使用這個變數及其屬性,在指令碼正在執行時,取得其相關資訊。例如, $MyInvocation.MyCommand.Path 變數包含指令碼的路徑和檔名。 Data 區段 您可以使用 Data 關鍵字在指令碼中將資料與邏輯分開。 Data 區段也可以讓當地語系化變得更加容易。如需詳細資訊,請參閱 about_Data_Sections 和 about_Script_Localization。 指令碼簽署 您可以為指令碼加上數位簽章。根據執行原則而定,您可以使用數位簽章,在指 令碼可能包含不安全的命令時,限制不得執行指令碼。如需詳細資訊,請參閱 about_Execution_Policies 和 about_Signing。 請參閱 about_Command_Precedence about_Comment_Based_Help about_Execution_Policies about_Functions about_Modules about_Profiles about_Requires about_Scopes about_Script_Blocks about_Signing Invoke-Command