Scaffolding Functions with Plaster

⚙️Reusable PowerShell functions with templates

In Part 1 of this blog post I covered how to create a module structure using Plaster. In this post I will cover how to create a function from a Plaster template. Plaster enables you to generate files consistently and resuse templates with having to copy and paste from other files.

The idea is very similar to creating a module structure with files ie you edit the manifest to include the parameters you want and in the content section you specify the template file to use for your function as well as any messages you want the user to see when they use your template. The main different is that the manifest you generate is of the Item TemplateType.

Create the Plaster Manifest File

$params = @{
    TemplateName = 'myFunction'
    TemplateType = 'Item'
    Description  = 'Function scaffolding'
    Author       = 'Art Vanderlay'
}
New-PlasterManifest @params

The New-PlasterManifest command generates a basic plastermanifest.xml file with metadata, parameters, and content sections.

Define Parameters

In this example I am going to use a combination of text, choice and multichoice parameters.

I have used the choice parameter for choosing whether you want comment based help with the choices yes or no. The choice parameter type allows for a single choice. I could have included this one in the multichoice option down below, but I wanted to illustrate how to use it.

Then I have used the multichoice parameter to select additional options such as ShouldProcess and ComputerName. The multichoice type of parameter allows you to select more than one choice.

👉🏼Note: Placing an ampersand before a character in the `label` serves as the "keyboard shortcut" for selecting the desired option.

For example, in the multichoice you have two options starting with C (ComputerName and ConfirmImpact). Therefore I placed & before the word Impact:

<choice label="Confirm&amp;Impact"
        help="Adds ConfirmImpact" value="ConfirmImpact" />

The ‘I’ would represent that option:

Content

Within the manifest you will also find a content section. Typically this would have less content than with the module. You would have the following to use a file as the source and then use the parameter Name which the user would input as the name of the generated file.

<templateFile source='function.ps1' destination='${PLASTER_PARAM_Name}.ps1' />

You can also include messages in the content to provide useful information:

<message>Your options where: $PLASTER_PARAM_options</message>

You can find the complete manifest for the function here:

Validate Manifest

After editing your manifest make sure to test if it is valid with the following:

 Test-PlasterManifest plastermanifest.xml -Verbose

Template file

In this example which I named function.ps1 is where you would use the input from parameters to decide what to include in the destination file.

The script expression delimiter is <% %> allows you to write some PowerShell which will be executed and any output would be added to a string array and inserted in the destination file. Below are parts of the file as an example.

If you need to include several lines as a string you would use a here string.

Use the template to create a function file

Assuming you have the function template file and manifest in a folder named Function on the C drive.

⚠️Note: Make sure you choose the path to the folder and not include the manifest file.

Invoke-Plaster -TemplatePath 'C:\function\' -DestinationPath "newcode"

This would start the menu options and prompt you for the function name and additional options. When finished you end up with a new ps1 file with the inserted text which would be a PowerShell function.

All the files are used can be found here GitHub Repository.

Summary

I guess it’s simpler to just have a Github gist with your perfect function with all the options you want and just copy and paste. But I liked the idea of using Plaster to keep templates organised and have a quick way to generate the file with the different options I like to have in functions since I may not want all of them.

Since I’ve been looking into ways to scaffold projects I have discovered the Sampler module, it has many purposes not just scaffolding a PowerShell module.

This is still evolving for me, so if you’ve got any suggestions please let me know. Also curious: What’s your setup when building out a PowerShell module?

Related Resources

• Modern PowerShell module Development

• The PowerShell Scripting and Toolmaking Book