about_scripts
主題
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 "遠端測試成功: $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。
指令碼範圍和 (.) 來源檔
每個指令碼都是在其個別的範圍內執行。在指令碼中建立的函數、變數、別名和磁碟
機都只存在指令碼範圍內，而且您不能在指令碼執行的範圍內存取這些項目或其值。
若要在不同的範圍中執行指令碼，您可以指定範圍 (例如「全域」或「本機」)，或是
在指令碼前加點。
(.) 來源檔功能可以讓您在目前的範圍 (而不是在指令碼範圍) 中執行指令碼。當
您執行指令碼前加點的指令碼時，指令碼中命令執行的方式就像在命令提示字元輸入
命令一樣。指令碼建立函數、變數、別名和磁碟機時，都會在您所使用的範圍內建立。
指令碼執行完成之後，您可以在自己的工作階段中使用其建立的項目並存取這些項目
的值。
若要在指令碼前加點，請在指令碼路徑前面輸入點 (.) 和空格。
例如：
. 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