通过

New-IseSnippet

  • 参考
模块:
ISE

创建 Windows PowerShell ISE 代码段。

语法

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

说明

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 在 $HOME\Documents\WindowsPowerShell\Snippets 目录中创建一个具有指定标题的 <Title>.Snippets.ps1xml 文件。 若要将代码段文件包含在你创作的模块中，请将代码段文件添加到模块目录的代码段子目录。

不能在执行策略为 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 创建一个 Comment-BasedHelp 代码段。 它在用户的代码片段目录 $HOME\Documents\WindowsPowerShell\Snippets 中创建一个名为 Comment-BasedHelp.snippets.ps1xml 的文件。

示例 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 将 Mandatory 代码片段从其所在文件夹（由 New-ISESnippet 放置到此文件夹）复制到 Server\Share 文件共享。

参数

-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 会话中，可以创建、获取和导入用户创建的未签名代码段，但无法在会话中使用它们。

如果你在 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 的代码段菜单中。