PowerShell Adapter Feedback Provider

We’ve renamed the JSON Adapter Feedback Provider to PowerShell Adapter Feedback Provider! We heard some good feedback that the name wasn’t as descriptive to what the feedback provider does so we’ve changed it to be more consistent with its functionality.

The Microsoft.PowerShell.PSAdapter is a module that identifies scripts and tools on the user machine that can help users more convert native command output into PowerShell objects. We designed this as a tool to help you discover what tools and scripts are available to help you convert native output to PowerShell objects.

Installing PowerShell Adapter Feedback Provider

The release is available from the PowerShell Gallery.

Use the following command to install using PowerShellGet v2.x:

Install-Module -Name Microsoft.PowerShell.PSAdapter -AllowPrerelease

If you are using PSResourceGet, you can use the following command:

Install-PSResource -Name Microsoft.PowerShell.PSAdapter -AllowPrerelease

To use it you must import the module into your session:

Import-Module Microsoft.PowerShell.PSAdapter

We encourage you to include this command in your $PROFILE so that it’s loaded in every PowerShell session you start.

What are PowerShell Adapters?

A PowerShell Adapter is a script that converts the text output of a native executable and converts it to PowerShell objects. The PowerShell Adapter module is a feedback provider that identifies these scripts and provides suggestions when you run the native command without any adapter script. You can read more about feedback providers in our blog post, What are feedback providers?.

You can make PowerShell Adapters for any command. Just use the exact name of the command as the prefix to the script so that the module can identify the script and suggest it. For example, you must name the script <name of command>-adapter.ps1 so that the PowerShell Adapter can identify it as a adapter script. This script’s file location must included in your $env:PATH variable to be found.

Creating an Adapter

For example, you want to use the macOS command vm_stat like a PowerShell object. Create a file called vm_stat-adapter.ps1 and add the location of this file to your $env:PATH variable. The PowerShell Adapter Feedback Provider will identify it as a possible suggestion for vm_stat.

Here is an example PowerShell Adapter for vm_stat:

[CmdletBinding()]
param ( [Parameter(ValueFromPipeline=$true)][string]$inputObject )
BEGIN {
    $h = @{}
}

PROCESS {
    if ( $inputObject -match "^Mach Virtual") {
        if ($inputObject -match "page size of (\d+) ") {
            $h['PageSize'] = [int]$matches[1]
        }
    }
    else {
        $k,$v = $inputObject -split ":"
        $AdjustedK = ($k -replace "[ -]","_").trim() -replace '"'
        $AdjustedV = "$v".Trim() -replace "\.$"
        $h[$AdjustedK] = [int64]$AdjustedV
    }
}

END {
    [pscustomobject]$h
}

The following shows the suggestion from the Feedback Provider when you run vm_stat without the adapter script:

For another example, we can create a PowerShell Adapter for the df utility using the TextUtility PowerShell module. We just need to create a df-adapter.ps1 script and include the following:

$input | ConvertFrom-TextTable -ConvertPropertyValue

Support for jc

The JSON Converter, jc, is a command line utility that converts text output to JSON for variety of command line tools. The PowerShell Adapter module can suggest using jc as an adapter if the user has it installed. When you use a command supported by jc, the PowerShell Adapter Feedback Provider suggests using jc piped to ConvertFrom-JSON.

You can find instructions on how to install jc and more details about the tool in their source code repository. When jc supports the native command, this can be the simplest way to convert the output without needing to write a PowerShell Adapter. You can see this suggestion in the previous screenshot for the df example.

"arp", "cksum", "crontab", "date", "df", "dig", "dir", "du", "file", "finger",
"free", "hash", "id", "ifconfig", "iostat", "jobs", "lsof", "mount", "mpstat",
"netstat", "route", "stat", "sysctl", "traceroute", "uname", "uptime", "w", "wc",
"who", "zipinfo"

Predictive IntelliSense Support

We’ve also added Predictive IntelliSense support for the PowerShell Adapter feedback provider. With Predictive IntelliSense enabled, the PowerShell Adapter Feedback Provider provides suggestions that Predictive IntelliSense will show you on the command line. This makes it easy to try immediately, rather than manually running the suggestion.

Feedback

We really appreciated the feedback we got on the first announcement of this tool and would love to continue getting great feedback! The GitHub repository for this tool is still named JSONAdapters, however the module name is Microsoft.PowerShell.PSAdapter and any reference to this tool will be PowerShell Adapters going forward. You can submit any feedback to the JsonAdapter repository.

Thank you so much!

Steven Bucher

PowerShell Team