Announcing 'Convert', a PowerShell Module for common object conversions.

I recently released a module to the PowerShell Gallery, called simply, Convert. Convert provides PowerShell Functions for common object conversions. The initial release enables conversions to and from base64 encoded strings, clixml, and MemoryStream objects with optional gzip compression. It wraps the appropriate .NET methods with easy to use PowerShell Functions. The module is cross-platform ready and comes with a minimum requirement of PowerShell 5, which I believe is fair game for 2018.

Installation is the standard process from the PowerShell Gallery:

Install-Module -Name 'Convert' -Scope 'CurrentUser'

I hear some of you asking, “what’s the benefit of a module that simply wraps standard .NET calls?” My answer, simplicity. I often perform object conversions between these object types, and I find myself forgetting the underlying .NET Namespace, or the conversion process. Instead, I want to use PowerShell to make this easier, and with Convert, hopefully to help other people while I’m at it.

How can Convert help you?

Do you ever want, or need to leverage clixml for handing objects around? Export-Clixml will handle the conversion, except it requires writing to disk, something I won’t do unless I absolutely must. You can use the System.Management.Automation.PSSerializer Namespace to perform the conversion in-memory, but I always forget the Namespace. With Convert, I only need to remember ConvertTo-Clixml and ConvertFrom-Clixml, both of which follow the standard “ConvertTo” and “ConvertFrom” naming convention for object conversions.

PS C:\> 'This is an object' | ConvertTo-Clixml

<Objs Version="1.1.0.1" xmlns="http://schemas.microsoft.com/powershell/2004/04">
  <S>This is an object</S>
</Objs>

What about some other examples where Convert may help?

Passing objects between disconnected systems with AWS Systems Manager, Parameter Store

Let’s say you have a process that invokes some PowerShell on a remote system, and you want to save a PowerShell Object somewhere for future retrieval, through a log file, database entry, or some other form of storage. Normally you would need to hunt down the code to do so, or write to the filesystem. Here’s an example using Convert and the AWS Systems Manager, Parameter Store to make this easy.

# On the remote system, save the 'Convert' module specification to AWS Parameter Store:
$base64 = Get-Module -Name 'Convert' | ConvertTo-Clixml | ConvertTo-Base64 -Compress
Write-SSMParameter -Name 'ConvertModuleSpec' -Value $base64 -Type String

# On a different system, retrieve the object back in its original form:
(Get-SSMParameterValue -Name 'ConvertModuleSpec').Parameters.Value | ConvertTo-String -Decompress | ConvertFrom-Clixml | Format-Table -AutoSize

ModuleType Version  Name    ExportedCommands
---------- -------  ----    ----------------
Script     0.1.1.13 convert {ConvertTo-String, ConvertFrom-MemoryStreamToString, ConvertTo-Clixml, ConvertFrom-MemoryStreamToBase64...}

Convert the output of an AWS Lambda Function

The Invoke-LMFunction PowerShell cmdlet (from AWSPowerShell or AWSPowerShell.NetCore) can be used to invoke an AWS Lambda Function. The invocation itself is easy, however the output is returned as a System.IO.MemoryStream object. Converting a MemoryStream to a String is a common process for Software Developers, but most PowerShell Developers won’t know this off the top of their head. With Convert this is easy; simply pipe the Payload property to ConvertTo-String.

$json = ConvertTo-Json -Compress -InputObject @{ 'name' = 'Andrew' }
(Invoke-LMFunction -FunctionName 'GetHelloWorld' -Payload $json).Payload | ConvertTo-String

{"Hello": "Andrew"}

To take this one step further, pipe the output to ConvertFrom-Json to create a PowerShell object to work with.

(Invoke-LMFunction -FunctionName 'GetHelloWorld' -Payload $json).Payload | ConvertTo-String | ConvertFrom-Json

Hello
-----
Andrew

Stream a PowerShell object to Amazon Simple Storage Service (S3)

The Write-S3Object PowerShell cmdlet (also from AWSPowerShell or AWSPowerShell.NetCore) is used to upload an object to S3. Common use-cases are to upload files and folders from your local filesystem, however the cmdlet also supports uploading data from a MemoryStream. Convert enables this with in-memory conversions from any object, to a MemoryStream object. Let’s see how.

$memoryStream = Get-Module -Name 'Convert' | ConvertTo-Clixml | ConvertTo-MemoryStream
Write-S3Object -BucketName 'mys3bucket' -Key 'ConvertModuleSpec.clixml' -Stream $memoryStream

So there you have it, I hope I’ve outlined why I released Convert to the PowerShell Gallery. It is available for installation today, and you can view the source code on GitHub.