PowerShell Script Module Design: Plaster Template for Creating Modules

I recently began updating my PowerShell script module build process. Updating my Plaster template was one of the first things I needed to do. If you haven’t already read my blog article about “Using Plaster to create a PowerShell Script Module template“, I’d recommend beginning there as this blog article assumes you already have a basic understanding of how to use Plaster.

All of the information from my previous Plaster template is still there with the exception of the required PowerShell version as I plan to obtain that information and update it a different way.

The first addition to my template that you’ll notice is the option to create both public and private folders within the module folder. By default, both of them are created.

The code shown in the previous example has a bug in it. See the update at the bottom of this blog article for the corrected code.

When I create a module (for development), I want to create a root folder as a Git repo and then the module’s root folder as a subfolder within that folder. I’ve added this ability to my Plaster template along with the option of not having the top level Git folder.

If the option to create the Git folder is selected (which is the default), then a conditional parameter asks for the name for the Git repo.

I ran into a problem with Plaster where paths for conditional parameters were validated even when the condition evaluated to false. As of this writing, Plaster version 1.1.3 is the newest version in the PowerShell Gallery and has this problem. Version 1.1.4 is available from GitHub and this problem is resolved in it. See this issue on GitHub for more details about the problem.

The final parameter is a multi-selection one and it’s also conditional based on whether or not creating a Git folder is selected.

The default selection adds an MIT license, a Readme.md file, and both .gitignore and .gitattributes files.

While those parameters are nice, they don’t do anything except ask questions. They need to be wired up to accomplish the desired tasks. The content section is where that happens.

I’ll use this template to create a new module named MrModuleBuildTools where I’ll be placing the tools that I’ll be creating to build PowerShell script modules.

At this point, I created a repo on GitHub for my ModuleBuildTools. I created it as a private repo until I’m ready to make it public.

One thing I haven’t figured out is if there’s a way to create the repo on GitHub from the command line?

Finally, I initialize the local folder as a Git repo, add all of the files that exist so far, commit them to the local repo, add the repo on GitHub as a remote, and push the changes to the repo on GitHub.

The basic structure for the development version of my MrModuleBuildTools PowerShell script module is now complete.

The xReadme.md template file contains the following content.

You might be wondering why the template file isn’t called Readme.md without the leading “x”? I didn’t want its content to show up on GitHub because it’s only meaningful to Plaster. Those variables are automatically replaced when the following line of the template is executed and the leading “x” is removed from the destination file during this process.

This means the first line is replace by whatever is specified as the “GitRepoName” and the third line is replaced by the “Description“.

The information in the MIT license is similar so that the current year is always specified along with the name of the module author.

My complete Plaster template can be found in my Plaster repository on GitHub. I used SAPIEN PrimalXML to format the XML in my template.

Be sure to keep an eye on this blog site as I’ll be adding tools to the MrModuleBuildTools module and blogging about them over the next few weeks.


Update – August 31, 2018

One of the huge benefits of open-sourcing your code and sharing it online is free code reviews! Tommy Maynard contacted me about a bug in the Public/Private folder creation process when my template is used manually with Invoke-Plaster. Which would your like? Select “P” or “P” as shown in the following example.

The letter for the hotkey is the character immediately after “&” so the solution is to simply shift it one (or more) place(s) to the right.

Thanks to Tommy for pointing out this bug! I’ve also made the corrections to the template in my Plaster repo on GitHub.

µ

4 Comments

  1. Sean Wheeler

    You can use the GitHub REST API to create your repo. See https://developer.github.com/v3/repos/#create.

    $header = @{
    Accept = ‘application/vnd.github.symmetra-preview+json’
    Authorization = “token ${Env:\GITHUB_OAUTH_TOKEN}”
    }
    $uri = ‘https://api.github.com/mikefrobbins/repos’

    $body = @’
    {
    “name”: “ModuleBuildTools”,
    “description”: “PowerShell Script Module Building Toolkit”,
    “private”: true,
    “license_template”, “mit”
    }
    ‘@

    $result = Invoke-RestMethod $uri -Method POST -header $header

    You need an OAUTH token from GitHub for $header.

    Reply

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: