New-IseSnippet

  • 參考
模組:
ISE

建立 Windows PowerShell ISE 代碼段。

Syntax

New-IseSnippet
   [-Title] <String>
   [-Description] <String>
   [-Text] <String>
   [-Author <String>]
   [-CaretOffset <Int32>]
   [-Force]
   [<CommonParameters>]

Description

Cmdlet New-ISESnippet 會為 Windows PowerShell ISE 建立可重複使用的文字「代碼段」。 您可以使用代碼段將文字新增至 Windows PowerShell ISE 中的 [腳本] 窗格或 [命令] 窗格。 此 Cmdlet 僅適用於 Windows PowerShell ISE。

從 Windows PowerShell 3.0 開始，Windows PowerShell ISE 包含內建代碼段的集合。 Cmdlet New-ISESnippet 可讓您建立自己的代碼段，以新增至內建集合。 您可以檢視、變更、新增、刪除和共用代碼段檔案，並將其包含在 Windows PowerShell 模組中。 若要查看 Windows PowerShell ISE 中的代碼段，請從 [編輯] 功能表中，選取 [開始代碼段] 或按 CTRL+J。

Cmdlet New-ISESnippet 會在目錄中建立 <Title>.Snippets.ps1xml 檔案， $HOME\Documents\WindowsPowerShell\Snippets 其中包含您指定的標題。 若要在您要撰寫的模組中包含代碼段檔案，請將代碼段檔案新增至模組目錄的代碼段子目錄。

您無法在執行原則為 Restricted 或 AllSigned 的工作階段中使用使用者建立的代碼段。

此 Cmdlet 已在 Windows PowerShell 3.0 中引進。

範例

範例 1：建立以批注為基礎的說明代碼段

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 建立批注型Help 代碼段。 它會在使用者的 Snippets 目錄中建立名為 Comment-BasedHelp.snippets.ps1xml 的檔案 $HOME\Documents\WindowsPowerShell\Snippets。

範例 2：建立強制代碼段

$M = @'
Param
(
  [parameter(Mandatory=$true)]
  [String[]]
  $<ParameterName>
)
'@

New-ISESnippet -Text $M -Title Mandatory -Description "Adds a mandatory function parameter." -Author "Patti Fuller, Fabrikam Corp." -Force

此範例會為 Windows PowerShell ISE 建立名為 Mandatory 的代碼 段。 第一個命令會將代碼段文字儲存在變數中 $M 。 第二個命令會 New-ISESnippet 使用 Cmdlet 來建立代碼段。 此命令會 使用 Force 參數，以相同名稱覆寫先前的代碼段。

範例 3：將強制代碼段從資料夾複製到目的地資料夾

Copy-Item "$HOME\Documents\WindowsPowerShell\Snippets\Mandatory.Snippets.ps1xml" -Destination "\\Server\Share"

此命令會Copy-Item使用 Cmdlet，從將它放置到 Server\Share 檔案共用的資料夾New-ISESnippet複製 [強制] 代碼段。

參數

-Author

指定代碼段的作者。 作者欄位會出現在代碼段檔案中，但當您按兩下 Windows PowerShell ISE 中的代碼段名稱時，它不會出現。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CaretOffset

指定此 Cmdlet 放置游標的代碼段文字字元。 輸入代表游標位置的整數，其中 「1」 代表文字的第一個字元。 預設值 0 （零），會將游標放在文字的第一個字元之前。 此參數不會縮排代碼段文字。

Type:Int32
Position:Named
Default value:0
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Description

指定代碼段的描述。 當您在 Windows PowerShell ISE 中按下代碼段名稱時，會出現描述值。 此為必要參數。

Type:String
Position:2
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Force

指出此 Cmdlet 會覆寫相同位置中同名的代碼段檔案。 根據預設， New-ISESnippet 不會覆寫檔案。

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Text

指定當您選取代碼段時所新增的文字值。 當您在 Windows PowerShell ISE 中按下代碼段名稱時，就會顯示代碼段文字。 此為必要參數。

Type:String
Position:3
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Title

指定代碼段的標題或名稱。 標題也會命名代碼段檔案。 此為必要參數。

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

None

此 Cmdlet 不會傳回任何輸出。

備註

New-IseSnippet 會將新的使用者建立代碼段儲存在未簽署的 .ps1xml 檔案中。 因此，Windows PowerShell 無法將它們新增至執行原則為 AllSigned 或 Restricted 的會話。 在 [受限制] 或 [所有簽署] 會話中，您可以建立、取得和匯入未簽署的使用者建立代碼段，但無法在會話中使用它們。

如果您在 Restricted 或 AllSigned 工作階段中使用 New-IseSnippetCmdlet，則會建立代碼段，但 Windows PowerShell 嘗試將新建立的代碼段新增至會話時，會出現錯誤訊息。 若要使用新的代碼段（以及其他未簽署的使用者建立代碼段），請變更執行原則，然後重新啟動 Windows PowerShell ISE。

如需 Windows PowerShell 執行原則的詳細資訊，請參閱 about_Execution_Policies。

  • 若要變更代碼段，請編輯代碼段檔案。 您可以在 Windows PowerShell ISE 的 [腳本] 窗格中編輯代碼段檔案。
  • 若要刪除您新增的代碼段，請刪除代碼段檔案。
  • 您無法刪除內建代碼段，但您可以使用 「$psise 隱藏所有內建代碼段。Options.ShowDefaultSnippets=$false“ 命令。
  • 您可以建立與內建代碼段同名的代碼段。 這兩個代碼段會出現在 Windows PowerShell ISE 的代碼段功能表中。