programming on Cory Knox

Everything you didn't know you didn't know about PSModuleDevelopment

Mon, 14 Jan 2019 00:00:00 +0000

Late in 2018, I had the distinct pleasure of spending a few hours with @FredWeinmann. We spent the time fixing up my PSCUCM Module (Available from the PowerShell Gallery and GitHub). During this session we went through a number of commands and setups utilizing his PSModuleDevelopment module and PSFramework. What will ensue is a multi-part series on Developing PowerShell Modules using PSFramework and PSModuleDevelopment.

And so, without further ado, I present part 1:

Setting up pre-requisites 🔗

We’re going to be using modules from the Powershell Framework Collective. Specifically: PSFramework and PSModuleDevelopment. However, I recommend looking at PSUtil as it contains some great functions that make working in PowerShell even more delightful.

Due to the way the PowerShell Gallery works you can install both modules with a single command: Install-Module PSModuleDevelopment -Scope CurrentUser

Setting up directory structures 🔗

With our modules installed, the first thing we need to do is setup our directory structures. To build a module prepared for Azure DevOps (formerly VSTS), we will use the PSFProject template that comes with PSModuleDevelopment. I encourage you to explore the various templates to see what’s available.

To get started we run the following code: Invoke-PSMDTemplate PSFProject This will prompt for a name and description, provide these and the function will establish the scaffolding for our project. The directory layout for a module called DemoModule will be something like the below:

DemoModule
├── build
│   ├── filesAfter.txt
│   ├── filesBefore.txt
│   ├── vsts-build.ps1
│   ├── vsts-prerequisites.ps1
│   └── vsts-validate.ps1
├── install.ps1
├── library
│   └── DemoModule
│       ├── DemoModule
│       │   ├── Class1.cs
│       │   └── DemoModule.csproj
│       └── DemoModule.sln
├── LICENSE
├── DemoModule
│   ├── bin
│   │   └── readme.md
│   ├── en-us
│   │   └── about_DemoModule.help.txt
│   ├── functions
│   │   └── readme.md
│   ├── internal
│   │   ├── configurations
│   │   │   ├── configuration.ps1
│   │   │   └── readme.md
│   │   ├── functions
│   │   │   └── readme.md
│   │   ├── scripts
│   │   │   ├── license.ps1
│   │   │   ├── postimport.ps1
│   │   │   └── preimport.ps1
│   │   └── tepp
│   │       ├── assignment.ps1
│   │       ├── example.tepp.ps1
│   │       └── readme.md
│   ├── DemoModule.psd1
│   ├── DemoModule.psm1
│   ├── readme.md
│   ├── tests
│   │   ├── functions
│   │   │   └── readme.md
│   │   ├── general
│   │   │   ├── FileIntegrity.Exceptions.ps1
│   │   │   ├── FileIntegrity.Tests.ps1
│   │   │   ├── Help.Exceptions.ps1
│   │   │   ├── Help.Tests.ps1
│   │   │   ├── Manifest.Tests.ps1
│   │   │   └── PSScriptAnalyzer.Tests.ps1
│   │   ├── pester.ps1
│   │   └── readme.md
│   └── xml
│       ├── DemoModule.Format.ps1xml
│       ├── DemoModule.Types.ps1xml
│       └── readme.md
└── README.md

Directory structure overview 🔗

First thing we will notice is that it created a directory titled DemoModule. This is clearly where we store our module and the related item. Of note is the numerous readme files present in the template. These will give you an overview of the areas that they are found so you can take further advantage of them. What follows is a sumarization in my own words what these directories are for, or at least what I use them for.

build 🔗

Within the DemoModule directory we have the build directory. This contains the scripts that are all preconfigured for use within an Azure DevOps pipeline. These will be covered in more depth in a coming installment of this series.

library 🔗

Next is the library. This contains the files and directories needed for a C# project that will result in a DLL. If we use this, it will automatically put he DLL into the appropriate places for the rest of our template to take advantage of. This is an area of the template I have not looked at, nor have I taken advantage of yet.

DemoModule 🔗

Up next is the DemoModule directory. This directory contains all of the files to actually make our module a module. This includes the manifest file, and the module file itself.

DemoModule/bin 🔗

The bin directory contains any binary data that is part of your module.

DemoModule/en-us 🔗

This is your Engligh US based help files. I haven’t made use of this yet, I’ve been using Comment Based Help… So you’re on your own for this one ¯_(ツ)_/¯

DemoModule/functions 🔗

Your public facing functions should be placed in the functions directory. The build scripts will expect this, and will check that you’re exporting every function that’s in here.

DemoModule/internal 🔗

Internal will contain the… Wait for it… internal components of our module. This includes configuration, functions, internal scripts, and tab expansion settings (tepp).

DemoModule/internal/configurations 🔗

Configurations will house the configurations for your module. In a PSFramework module you will likely put your PSFConfig initializations in here.

DemoModule/internal/functions 🔗

Functions will house the internal functions. These are typically functions that do make things easier for your when developing the module, but don’t need to extend beyond the module. Examples may be consistently fetching certain data, or creating objects consistently. Basically anything that you will need to do multiple times but the end user won’t need to do should go in this directory. These functions should also follow best practices and follow the Verb-Noun principal with approved verbs.

DemoModule/internal/scripts 🔗

The default scripts are: license.ps1, preimport.ps1, and postimport.ps1. These files contain your license (default is MIT license), any commands that should be processed before your module is imported (perhaps some verification of module or application installations?), and the commands to be processed after your module is imported. By default the preimport.ps1 is effectively empty. The important file in the default scaffolding is the postimport.ps1 file. This file will import all of your configurations, your tab expansion, and finally your license.

DemoModule/internal/tepp 🔗

At last we reach the tepp directory… tepp stands for Tab Expansion Plus Plus. This is the module that first brough tab expansion to PowerShell. PSFramework includes functions for registering these tab expansions that work by default in Windows 10 running PowerShell 5, as well as PowerShell 6 on all Operating Systems that I’ve tested it on. The benefit of registering tab expansion over using a ValidateSet is that a ValidateSet requires that the parameter match the set, while a tepp registered set is only some of the possible entries. For instance, in creating a custom wrapper for PSCUCM’s New-Phone function, I could register tab expansions for the phones that we have. This allows new phones to be added without the need to immediately update the tepp as you could just specify the new phone. A ValidateSet would require that we update the set prior to trying to use the new phone with the function.

DemoModule/tests 🔗

The tests directory. This contains all the tests that you’re obviously going to include with your module…

DemoModule/tests/functions 🔗

The functions directory within tests is for your modules functions. You can divide this directory up as you see fit. If you’re going to test your internal functions (and why wouldn’t you?), then you might want a internal directory. My recommendation would be to follow the structure that you use for your public functions, and to have a test file for each function file.

DemoModule/tests/general 🔗

The general directory contains the tests included with the scaffolding. These tests will check all of your functions for some form of help for all parameters. It will check the Examples for a description (if using comment based help, the description comes after a blank line following the example).

DemoModule/xml 🔗

The xml directory contains the Type and Format Definitions for your module. The PSModuleDevelopment includes some helpful functions for creating these xml files so you don’t need to work with them by hand. If you have need for some of these files, I highly recommend investigating the readme file within as it does an excellent job of describing the process.

Conclusion 🔗

Now that we’ve gone over the basics of getting started, you can go out and get your own modules started. Stay tuned for part 2 where we’ll take our next step in the journey.

A Foray into vscode-powershell

Mon, 03 Sep 2018 00:00:00 +0000

This is a foray into getting started with the vscode-powershell extension. In particular noting some of the perhaps less obvious things I needed to do in order to get it to build on Ubuntu 18.04.

First thing you’ll need to do of course is to fork the repository. There are two repositories that we want to fork to our github account: PowerShellEditorService and vscode-powershell. Once you’ve forked them (and perhaps made hours of work that Tiler and Rob keep harrassing you as not being good enough…) you need to clone them to your local machine. I highly recommend keeping them side by side and so I clone them into a repos directory. On my Windows machine all of my git repos are stored at C:\repos\ on my fresh install of Ubuntu Linux 18.04 they’re stored at ~/git/.

System software to install 🔗

Now after freshly installing Ubuntu 18.04, I have installed the following software on top of the base:

PowerShell-Preview - PowerShell 6.1 is in Release Candidate, and is the only “Supported” version for Ubuntu 18.04
npm - Not entirely sure if I installed this one, or if it’s just installed as part of Ubuntu… It’s definitely installed though.
VS Code Insiders

Once this is installed, and the repos are cloned. I opened vscode-powershell in vscode-insiders. I then selected Debug > Start Debugging This greeted me with the message: “The preLaunchTask ‘BuildAll’ terminated with exit code 1.” Clearly we’re missing some pre-requisites… Looking in the terminal we see:

> Executing task: Invoke-Build BuildAll <

execvp(3) failed.: No such file or directory
The terminal process terminated with exit code: 1

Terminal will be reused by tasks, press any key to close it.

This initially felt like we were missing InvokeBuild from the PowerShell Gallery. Unfortunately, after installing that, the error is still present. The build appears to work if we do Invoke-Build from pwsh-preview.

It turns out that this is the trick here. We’re using a preview build of pwsh on Ubuntu 18.04, because that is what’s available. To resolve this, we can simply create a symlink from pwsh to pwsh-preview… This may need to be resolved once pwsh 6.1 leaves Release Candidate, or the installation of pwsh may resolve it for us. To create the symlink: sudo ln -s /usr/bin/pwsh-preview /usr/bin/pwsh. Once this symlink is created, debugging of both vscode-powershell and PowerShellEditorServices seems to go off without a hitch.

Conclusion 🔗

Once getting over the hurdle of pwsh not being available outside of a preview on Ubuntu 18.04, getting vscode-powershell and PowerShellEditorServices development going in Ubuntu 18.04 is actually really easy, and dare I say may be even easier than doing the same thing on Windows 10…

I did note while investigating the pwsh-preview issue that there are already documents that may provide more information (and will at least be more up to date than this document) here: vscode-powershell Development Document and here: PowerShellEditorServices ReadMe.

Azure Functions FTW - Using Azure Functions to schedule GitHub Pages posts

Wed, 29 Aug 2018 00:00:00 +0000

If you’re reading this… And it’s after August 29th 2018 at 9 AM PDT… Then that means it worked. I mean I know it works because this isn’t the first post of it’s kind, but it’s the first I’m actually going to keep up.

It all started when I was discussing having finally setup this blog on Twitter. Someone asked if I could schedule blog posts. At the time I didn’t know if it was possible, but a simple web search found the answer over here: Scheduling posts on Github pages with AWS lambda functions by: Evert Pot Of course, this is fine and dandy if you already have AWS. But! What if you have Azure? Could you do something similar with it?

Setup 🔗

From what I could make of AWS lambda functions they are somewhat analogous to Azure Functions. It appears that the billing is somewhat similar, and different as we’ll see. First we need to setup an Azure Function App within our Azure account. I’ll leave that as an exercise for the user, but hit me up in the comments or on Twitter if you need some pointers.

Once I had the Azure Function App setup, I attempted to make a javascript function following the code provided by Evert. Unfortunately it would seem some of the conventions used don’t work with Azure Functions (although it seems perhaps they do, you just need to turn on a preview of v2 or something of the like). The main thing I was tripping on was that await and async didn’t seem to be available. Further, no matter what I did, the query was always returning undefined. Instead of fight with a language I understand, but in a runspace I do not understand, I started investigating if it could be done with PowerShell. Looking at the github API documentation, it looks fairly straight forward. You send a request to the API, and it either returns success, or it returns 404.

After determining that we could do this with an Invoke-RestMethod in PowerShell, the next step was to setup the PowerShell function. Within the Function App you want to enable Experimental Language support and then add a new timer trigger. Like Evert, I have mine set to fire every hour on the hour. Once we’ve created the function, we need to populate it with the code.

Code 🔗

The below is not fully tested in production. As with most things, I got the command working and have left it as is for my setup. However, for this blog post we need it to be a tad prettier… so I have moved the username and token into variables and expanded the command from irm. I’m open to Pull Requests should this not function properly.

$Token = 'YourGitHubToken'
$Username = 'YourGitHubUsername'
$InvokeRestMethodSplat = @{
    Uri = "https://api.github.com/repos/$Username/$Username.github.io/pages/builds"
    Method = Post
    Headers = @{
        Authorization = "token $Token"
        Accept = 'application/vnd.github.mister-fantastic-preview+json' }
}
Invoke-RestMethod @InvokeRestMethodSplat

Break it on down 🔗

I’m trying not to reproduce everything that Evert, but the basic breakdown as listed on his article:

Create a Personal Access Token on GitHub.
Make sure you give it at least the repo and user privileges.
Make sure you add future: false to your _config.yaml.
Write a blog post, and set the date to some point in the future.

Once we’ve setup the Token, and set our _config.yaml properly, we can go ahead with the function. If we check out the GitHub API documentation we’ll see that we can just make a simple web request to the API endpoint with our token and voila it initiates a build.

Costs 🔗

I told you I’d get to costs… Unfortunately, it is looking like this isn’t quite as cheap as AWS lambda functions. I haven’t gone a full billing cycle, but at 9 days in, this is showing as costing $0.01 CAD so far. This isn’t due to runtime of the function though. This is due entirely to the underlying storage costs. Apparently we need to pay for somewhere to store our function. And really, if it’s going to cost us a few pennies a month, it’s close enough to free.

Caveats 🔗

One thing to be aware of, if you use the RSS feed. Every time this function fires, the date at the top of the RSS file updates (this also makes a convenient place to check if it’s running). I don’t believe this to be an issue for anything, but perhaps if you use a feed reader you could let me know if you see duplicate posts or anything strange.

Next steps/Follow-up 🔗

I will try to remind myself to update this post when my Azure month rolls over in Mid September. I fully expect that costs shouldn’t change much.

So you want to make a VS Code extension

Tue, 03 Jul 2018 00:00:00 +0000

So, you have this great idea for a VS Code extension? But perhaps you’re thinking “where do I start?” Well, fear not! for I have written this post to tell you the answer!

Oh? Were you expecting me to have the answer? Well, you see the truth is I have no idea. I just took some code, put some other code in it, and it worked (well sorta).

But for reals: Decide if you want to use TypeScript or JavaScript (I picked TypeScript because all the samples were in TypeScript). Then take a look at https://code.visualstudio.com/docs/extensions/example-hello-world to get your first example done.

If like me you have little experience with TypeScript, it is worth reading through this one to try and understand what it is doing. Also take a look at the examples: https://github.com/Microsoft/vscode-extension-samples I went here to look at the tree-view-sample for the one I’m working on.