.png)
New-IseSnippet
New-IseSnippet
Syntax
Parameter Set: Default New-IseSnippet [-Title] <String> [-Description] <String> [-Text] <String> [-Author <String> ] [-CaretOffset <Int32> ] [-Force] [ <CommonParameters>]
Detailed Description
The New-ISESnippet cmdlet creates a reusable text "snippet" for Windows PowerShell ISE. You can use snippets to add text to the Script pane or Command pane in Windows PowerShell ISE. This cmdlet is available only in Windows PowerShell ISE.
Beginning in Windows PowerShell 3.0, Windows PowerShell ISE includes a collection of built-in snippets. The New-ISESnippet cmdlet lets you create your own snippets to add to the built-in collection. You can view, change, add, delete, and share snippet files and include them in Windows PowerShell modules. To see snippets in Windows PowerShell ISE, from the Edit menu, select Start Snippets or press Ctrl+J.
The New-ISESnippet cmdlet creates a <Title>.Snippets.ps1xml file in the $home\Documents\WindowsPowerShell\Snippets directory with the title that you specify. To include a snippet file in a module that you are authoring, add the snippet file to a Snippets subdirectory of your module directory.
This cmdlet is introduced in Windows PowerShell 3.0.
Parameters
-Author<String>
Identifies the author of the snippet. The author field appears in the snippet file, but it does not appear when you click the snippet name in Windows PowerShell ISE.
Aliases | none |
Required? | false |
Position? | named |
Default Value | None (no value) |
Accept Pipeline Input? | false |
Accept Wildcard Characters? | false |
-CaretOffset<Int32>
Places the cursor on the specified character of the snippet text. Enter an integer that represents the cursor position, with "1" representing the first character of text. The default value, 0 (zero), places the cursor immediately before the first character of text. This parameter does not indent the snippet text.
Aliases | none |
Required? | false |
Position? | named |
Default Value | 0 |
Accept Pipeline Input? | false |
Accept Wildcard Characters? | false |
-Description<String>
Provides a description of the snippet. The description value appears when you click the snippet name in Windows PowerShell ISE. This parameter is required.
Aliases | none |
Required? | true |
Position? | 2 |
Default Value | None |
Accept Pipeline Input? | false |
Accept Wildcard Characters? | false |
-Force
Overwrites snippet files with the same name in the same location. By default, New-ISESnippet does not overwrite files.
Aliases | none |
Required? | false |
Position? | named |
Default Value | False |
Accept Pipeline Input? | false |
Accept Wildcard Characters? | false |
-Text<String>
Specifies the text value that is added when you select the snippet. The snippet text appears when you click the snippet name in Windows PowerShell ISE. This parameter is mandatory.
Aliases | none |
Required? | true |
Position? | 3 |
Default Value | false |
Accept Pipeline Input? | false |
Accept Wildcard Characters? | false |
-Title<String>
Specifies a title or name for the snippet. The title also names the snippet file. This parameter is mandatory.
Aliases | none |
Required? | true |
Position? | 1 |
Default Value | None |
Accept Pipeline Input? | false |
Accept Wildcard Characters? | false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).
Inputs
The input type is the type of the objects that you can pipe to the cmdlet.
- None
This cmdlet does not take input from the pipeline.
Outputs
The output type is the type of the objects that the cmdlet emits.
- None
This cmdlet does not generate any output.
Notes
-- To change a snippet, edit the snippet file. You can edit snippet files in the Script pane of Windows PowerShell ISE.
-- To delete a snippet that you added, delete the snippet file.
-- You cannot delete a built-in snippet, but you can hide all built-in snippets by using the "$psise.Options.ShowDefaultSnippets=$false" command.
-- You can create a snippet that has the same name as a built-in snippet. Both snippets appear in the snippet menu in Windows PowerShell ISE.
Examples
-------------------------- EXAMPLE 1 --------------------------
This command creates a Script Title snippet for Windows PowerShell ISE. It creates a file named "ScriptTitle.Snippets.ps1xml" in the user's Snippets directory ($home\Documents\WindowsPowerShell\Snippets).
PS C:\>New-ISESnippet -Title "ScriptTitle" -Text "# <Script title goes here> by Paul Shen" -Description "Comment line for script title"
-------------------------- EXAMPLE 2 --------------------------
These commands create a Mandatory snippet for Windows PowerShell ISE. The first command saves the snippet text in the $m variable. The second command uses the New-ISESnippet cmdlet to create the snippet. The command uses the Force parameter to overwrite a previous snippet with the same name.
PS C:\>$m = @'Param([parameter(Mandatory=$true)][String[]]$<ParameterName>)'@PS C:\>New-ISESnippet -Text $m -Title Mandatory -Description "Adds a mandatory function parameter." -Author "Kim Akers, Fabrikam Corp." -Force
-------------------------- EXAMPLE 3 --------------------------
This command uses the Copy-Item cmdlet to copy the Mandatory snippet from the folder where New-ISESnippet places it to the Server\Share file share.
Because the Snippets.ps1xml files that New-ISESnippet creates are text (XML) files, you can use the Item cmdlets to get, changes, move, rename, and copy them.
PS C:\>Copy-Item $home\Documents\WindowsPowerShell\Snippets\Mandatory.Snippets.ps1xml -Destination \\Server\Share
Related topics
