PowerShell Adapter Feedback Provider

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 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 are available to help you convert native
output to PowerShell objects.

Note


Feedback Providers are an experimental feature of 7.4-preview3+ and so you will be required to use one of the 7.4 previews for JSON Adapters to work and have `PSFeedbackProvider` experimental feature enabled .

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
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 -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:

Screenshot showing vm_stat suggestions.

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

DF utility adapter

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 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.

The jc command supports many native commands, however, the Feedback Provider only provides jc
suggestions for the following commands:
"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"

Also, you need to use the appropriate parameters with your native command for jc to work properly.
For example, if you want to use jc with uname, you need to use uname -a because that produces
the output that jc expect to convert to JSON.

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.

Screenshot showing predictive intellisense support

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

The post PowerShell Adapter Feedback Provider appeared first on PowerShell Team.

 

This article was originally published by Microsoft's Secure Blog. You can find the original article here.