PowerShell Studio Templates : Get a head start on your scripts

November 19th, 2014 by June Blender
Last updated on November 18th, 2014

 

When you open a new script file (.ps1) in PowerShell Studio 2014, you don’t get a blank page, at least by default. Instead, the page begins with a comment block, like this one:

<#
.NOTES
===========================================================================
Created with:     SAPIEN Technologies, Inc., PowerShell Studio 2014 v4.1.74
Created on:       11/5/2014 4:28 PM
Created by:       juneb
Organization:     SAPIEN
Filename:
===========================================================================
.DESCRIPTION
A description of the file.
#>

 

This text comes from a template that contains starter text for new script files. In this post, I’ll explain how templates for script files work. I’ll show you where we keep default templates and tell how you can a blank template if you’d like one. In a later post, I’ll show you how to create more complex templates and delve into templates for forms.

 

What is a template?

When you create a new file in PowerShell Studio, instead of starting from scratch every time, we give you a head start. Our starter files, called templates, free you from typing the same boilerplate text in every file.

The template text is added to your file only once – when you create the file – and we never change it, update it, or add to it, because PowerShell Studio never edits your files unless you request it.

To select a template, PowerShell Studio uses the file name extension, such as .ps1, .psm1, .psd1, or .psf, to find a template for that file type. If you have just one template for a file type, PowerShell Studio inserts the template text into the file automatically. If you have more than one template for a file type, we pop up a list of your templates and let you choose one.

I’ve created several templates for .ps1 script files, so when I create a new one, I get to choose the template.

image

 

Where are my script file templates?

We keep the default, read-only templates in a SAPIEN directory and a your personal templates in your roaming user profile.

  • Default templates – the ones that come with PowerShell Studio:C:\ProgramData\SAPIEN\PowerShell Studio 2014\Templates\FileTypes

They’re all named PowerShell Studio Template.

image

  • Custom templates – the ones that you create:$home\AppData\Roaming\SAPIEN\PowerShell Studio 2014\Templates\FileTypes

 

You can select names for your custom templates, but you can’t edit the default templates or move the template directories. If you do, PowerShell Studio won’t be able to find them.

 

Default script template: It’s help!

The default script file template, PowerShell Studio Template.ps1, is pretty awesome.

<#
.NOTES
===========================================================================
Created with:     SAPIEN Technologies, Inc., PowerShell Studio 2014 v4.1.74
Created on:       11/5/2014 4:28 PM
Created by:       juneb
Organization:     SAPIEN
Filename:
===========================================================================
.DESCRIPTION
A description of the file.
#>

 

It’s a comment block, but this is no ordinary comment block. It’s a comment-based help block that uses the format and syntax that the Get-Help cmdlet recognizes. Even if you don’t add anything to the comment block, the default template for PowerShell Studio 2014 scripts helps you to fulfill one of the most important scripting best practices: providing help for your scripts and for the functions that the script exports.

When you save your script file and run the Get-Help cmdlet with the path to the script file, Get-Help gets the content of the comment block and displays it as help for the script, just like it would display help for a cmdlet. But, when you get help for a script, Get-Help requires the path and name of the script as the value of the Name parameter, just like it requires the path and name to run the script.

For example, if my script file is Test-Template.ps1 in the C:\ps-test directory, I can run this command:

    Get-Help –Name C:\ps-test\Test-Template.ps1 -Full

And get this result. Windows PowerShell interprets the comment block as help. And, I haven’t even edited it.

NAME
C:\ps-test\Test-Template.ps1

SYNOPSIS

SYNTAX
C:\ps-test\Test-Template.ps1 [<CommonParameters>]

DESCRIPTION
A description of the file.

PARAMETERS
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (
http://go.microsoft.com/fwlink/?LinkID=113216).

INPUTS

OUTPUTS

NOTES

        ===========================================================================
Created with:     SAPIEN Technologies, Inc., PowerShell Studio 2014 v4.1.74
Created on:       11/5/2014 4:28 PM
Created by:       JuneBlender
Organization:     SAPIEN Technologies, Inc.
Filename:
===========================================================================

RELATED LINKS

Want to know more about comment-based help? See the about_Comment_Based_Help topic.

 

I want a blank file

Sometimes, you just want to start with a blank script file. I use a blank file when I’m testing new ideas. I don’t expect to save the file or use it for a script.

Here’s how you do it.

  1. In PowerShell Studio 2014, create a new PowerShell script file (.ps1). One way is to click File –> New –> New PowerShell Script.image
  2. Delete the comment-based-help block, so you have a blank page.image
  3. Click File and then click Create Template.image

    PowerShell Studio opens the template directory in your roaming user profile.

  4. Type a name for your template file and then click Save. (I chose Blank.ps1.) Be sure to leave the file name extension as .ps1, so it matches the extension of PowerShell scripts.

image

Done! You can use the blank script file that you used to create the template or close it without saving.

Now, when you create a new script file, Blank is one of your choices.

image

June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at juneb@sapien.com or follow her on Twitter at @juneb_get_help.

 

 
[Google+]   [Facebook]   [LinkedIn]   [StumbleUpon]   [Digg]   [Reddit]   [Google Bookmark]  

Tags: ,