New-IseSnippet
建立 Windows PowerShell ISE 代碼段。
語法
Default (預設值)
New-IseSnippet
[-Title] <String>
[-Description] <String>
[-Text] <String>
[-Author <String>]
[-CaretOffset <Int32>]
[-Force]
[<CommonParameters>]
Description
New-ISESnippet Cmdlet 會為 Windows PowerShell ISE 建立可重複使用的文字“代碼段”。 您可以使用代碼段將文字新增至 Windows PowerShell ISE 中的 [腳本] 窗格或 [命令] 窗格。 此 Cmdlet 僅適用於 Windows PowerShell ISE。
從 Windows PowerShell 3.0 開始，Windows PowerShell ISE 包含內建代碼段的集合。 New-ISESnippet Cmdlet 可讓您建立自己的代碼段，以新增至內建集合。 您可以檢視、變更、新增、刪除和共用代碼段檔案，並將其包含在 Windows PowerShell 模組中。 若要查看 Windows PowerShell ISE 中的代碼段，請從 [編輯] 功能表中，選取 [開始代碼段] ，或按 CTRL+J。
New-ISESnippet Cmdlet 會建立 <Title>。$home\Documents\WindowsPowerShell\Snippets 目錄中的 Snippets.ps1xml 檔案，其中包含您指定的標題。 若要在您要撰寫的模組中包含代碼段檔案，請將代碼段檔案新增至模組目錄的代碼段子目錄。
您無法在執行原則 受限制 或 AllSigned的工作階段中使用使用者建立的代碼段。
此 Cmdlet 已在 Windows PowerShell 3.0 中引進。
範例
範例 1：建立 Comment-BasedHelp 代碼段
PS C:\> New-IseSnippet -Title Comment-BasedHelp -Description "A template for comment-based help." -Text "<#
.SYNOPSIS
.DESCRIPTION
.PARAMETER <Parameter-Name>
.INPUTS
.OUTPUTS
.EXAMPLE
.LINK
#>"
此命令會為 Windows PowerShell ISE 建立 Comment-BasedHelp 代碼段。 它會在使用者的 Snippets 目錄中建立名為 「Comment-BasedHelp.snippets.ps1xml」 的檔案（$home\Documents\WindowsPowerShell\Snippets）。
範例 2：建立強制代碼段
PS C:\> $M = @'
Param
(
[parameter(Mandatory=$true)]
[String[]]
$<ParameterName>
)
'@
PS C:\> New-ISESnippet -Text $M -Title Mandatory -Description "Adds a mandatory function parameter." -Author "Patti Fuller, Fabrikam Corp." -Force
此範例會建立 Windows PowerShell ISE 的必要代碼段。 第一個命令會將代碼段文字儲存在 $M 變數中。 第二個命令會使用 New-ISESnippet Cmdlet 來建立代碼段。 此命令會使用 Force 參數，以相同名稱覆寫先前的代碼段。
範例 3：將強制代碼段從資料夾複製到目的地資料夾
PS C:\> Copy-Item "$Home\Documents\WindowsPowerShell\Snippets\Mandatory.Snippets.ps1xml" -Destination "\\Server\Share"
此命令會使用 Copy-Item Cmdlet，從 New-ISESnippet 資料夾複製強制代碼段， 將它放在 Server\Share 檔案共用。
因為 New-ISESnippet 建立的 Snippets.ps1xml 檔案是文字 （XML） 檔案，因此您可以使用 Item Cmdlet 來取得、變更、移動、重新命名及複製它們。
參數
-Author
指定代碼段的作者。 作者欄位會出現在代碼段檔案中，但當您按兩下 Windows PowerShell ISE 中的代碼段名稱時，它不會出現。
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-CaretOffset
指定此 Cmdlet 放置游標的代碼段文字字元。 輸入代表游標位置的整數，其中 「1」 代表文字的第一個字元。 預設值 0 （零），會將游標放在文字的第一個字元之前。 此參數不會縮排代碼段文字。
參數屬性
| 類型: | Int32 |
| 預設值: | 0 |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-Description
指定代碼段的描述。 當您在 Windows PowerShell ISE 中按下代碼段名稱時，會出現描述值。 這是必要參數。
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | 2 |
| 必要: | True |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-Force
指出此 Cmdlet 會覆寫相同位置中同名的代碼段檔案。 根據預設，New-ISESnippet 不會覆寫檔案。
參數屬性
| 類型: | SwitchParameter |
| 預設值: | False |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | Named |
| 必要: | False |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-Text
指定當您選取代碼段時所新增的文字值。 當您在 Windows PowerShell ISE 中按下代碼段名稱時，就會顯示代碼段文字。 這是必要參數。
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | 3 |
| 必要: | True |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
-Title
指定代碼段的標題或名稱。 標題也會命名代碼段檔案。 這是必要參數。
參數屬性
| 類型: | String |
| 預設值: | None |
| 支援萬用字元: | False |
| 不要顯示: | False |
參數集
(All)
| Position: | 1 |
| 必要: | True |
| 來自管線的值: | False |
| 來自管線按屬性名稱的值: | False |
| 來自剩餘引數的值: | False |
CommonParameters
此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。
輸入
None
此 Cmdlet 不會從管線取得輸入。
輸出
None
此 Cmdlet 不會產生任何輸出。
備註
- New-IseSnippet 會將新的使用者建立代碼段儲存在未簽署的 .ps1xml 檔案中。 因此，Windows PowerShell 無法將它們新增至執行原則 AllSigned 或 Restricted的會話。 在 限制 或 AllSigned 工作階段中，您可以建立、取得和匯入未簽署的使用者建立代碼段，但無法在工作階段中使用它們。
如果您在 Restricted 或 AllSigned 會話中使用 New-IseSnippet Cmdlet，則會建立代碼段，但 Windows PowerShell 嘗試將新建立的代碼段新增至會話時，會出現錯誤訊息。 若要使用新的代碼段（以及其他未簽署的使用者建立代碼段），請變更執行原則，然後重新啟動 Windows PowerShell ISE。
如需 Windows PowerShell 執行原則的詳細資訊，請參閱about_Execution_Policies。
若要變更代碼段，請編輯代碼段檔案。 您可以在 Windows PowerShell ISE 的 [腳本] 窗格中編輯代碼段檔案。
若要刪除您新增的代碼段，請刪除代碼段檔案。
您無法刪除內建代碼段，但您可以使用 「$psise 隱藏所有內建代碼段。Options.ShowDefaultSnippets=$false“ 命令。
您可以建立與內建代碼段同名的代碼段。 這兩個代碼段會出現在 Windows PowerShell ISE 的代碼段功能表中。