Interactive instruction search using the Tachyon PowerShell Toolkit
The Tachyon Explorer UI contains an interactive search dialogue for finding and executing Tachyon instructions. The interactive instruction search feature provides you with similar capabilities, but directly from the PowerShell command window.
Interactive search allows you to do the following.
Interactively find and execute an instruction
Interactively find an instruction and automatically create a PowerShell cmdlet from it - the cmdlet can then be run at any time, just like any regular PowerShell cmdlet
Interactively find an instruction and then export it to an XML instruction file.
Note
The single-character input method used by interactive search is not available in the PowerShell ISE and so you cannot single-step through the interactive search code in the ISE. Every other feature of the PowerShell integration Toolkit is debuggable in the ISE except for this one.
Getting started with interactive instruction search
To initiate an interactive search, enter the PowerShell command.
search-tachyoninstruction
Note
You cannot use this cmdlet from the PowerShell ISE, only from a standard PowerShell prompt. This is because the ISE does not fully emulate the PowerShell environment. The interactive search relies on being able to trap and process single keystrokes, and uses functionality that the ISE does not emulate.
This cmdlet was called search-tachyonserver in versions of the toolkit prior to 1.0.2
You will see the following screen displayed.
Start typing your search just as you would in the Tachyon Explorer. Instructions which match your search are shown as you type.
As you continue typing, the list of available instructions will shrink. When it reaches ten or less, the top bar turns green and the instructions are displayed with a number from 0 to 9 in front of each one.
Questions are shown in green. Actions are shown in amber.
Note
Actions potentially change device state and require workflow approval. You can launch either an action or a question from the interactive search, but if you launch an action, it will not return results until you approve it.
For more information on workflow and the Tachyon PowerShell Toolkit, see Workflow management cmdlets.
Select an instruction by entering the number associated with the instruction. You will now see a screen displayed confirming your selection and prompting for parameters.
Enter the parameters required. These will vary depending on the instruction invoked.
You will always be prompted to supply a target scope; in this case, we have requested all devices whose FQDN contains URTH.
Note that the instruction invoked was an aggregating instruction. By default, the results are shown aggregated. You can override this by specifying a command line parameter that specifies that aggregating instructions should instead have the results displayed as details instead. This is discussed in the section on 'Search Command Line Parameters' below.
Note
You may note that some of the returned instructions in the above list did not contain the string 'devices' in their readable payload. This is because the Tachyon search API, also used by Explorer, additionally searches the instruction description for any matches and returns these instructions as well.
Selecting a single instruction
If the search list reduces to a single instruction, then the search bar turns green but no digit is displayed next to the instruction. To select this instruction, simply press RETURN.
Exiting the search without selecting an instruction
To exit the search without selecting an instruction, either press ctrl+C or, with the search line blank, simply press RETURN.
Note
To remove existing typed text, use the backspace key
Interactive Search Command Line Arguments
You can specify the following optional arguments to the tachyon-search command.
Parameter | Description |
|---|---|
-PromptDefaults | If specified, causes any instruction parameters which have default values to be prompted for, with the default auto-filled in. Normally if this flag is not specified, instruction parameters with defaults cause the instruction to be invoked with those defaults automatically. Only instruction parameters without defaults are prompted for, unless this option is set. |
-Drilldown | If specified, causes any aggregating instruction to be displayed at detail level instead of at aggregated level. |
-TargetScope <device pattern> | If specified, uses the specified device FQDN pattern for the target scope of any selected instruction. You are prompted to supply this otherwise when you execute an instruction from the search Note that Tachyon supports more complex target scoping expressions. You can supply a scoping expression instead of a simple pattern match. For more information see Using scope and filter expressions with the Tachyon PowerShell Toolkit |
-TargetFqdns <array of FQDNS> | If specified, the array of FQDNs is the target scope of any selected instruction. This parameter is mutually exclusive with the -TargetScope parameter. |
-CreateCmdlet | If specified, indicates that instead of running the instruction, a cmdlet will be created from it automatically, for re-use later. This option is discussed in the section on 'Creating Cmdlets' below. When this option is specified, the -Drilldown, -TargetScope and -TargetFqdns parameters are ignored. |
-Export | If specified indicates that instead of running the instruction, it will be exported as a ZIP file. This option is mutually exclusive with the -CreateCmdlet option and similarly the -Drilldown, -TargetScope and -TargetFqdns parameters are ignored when it is specified |
Creating cmdlets from interactive search
You can use the interactive search instruction to locate a Tachyon instruction and then package that as a cmdlet for re-use within the PowerShell environment. To do this, invoke the search-tachyonserver instruction with the -CreateCmdlet parameter.
The search process is identical to the normal instruction search. However, once you have selected an instruction, you will be prompted for the cmdlet name you want to associate it with, as shown below
 |
 |
A cmdlet file, get-localaccounts.psm1 is created in the current folder
To use the cmdlet, import it into your PowerShell session with
import-module .\get-localaccounts.psm1 -force
Note
I recommend the -force parameter in case you have a modified version of the cmdlet from an older instruction still in your PowerShell cache. This will force PowerShell to always load the latest version of the module
You can then invoke the cmdlet as shown in the screenshot below. Note that the cmdlet was invoked twice. As an aggregating command, you can use the -Drilldown parameter to show details instead of the aggregated results
Exporting instructions
You can specify the -Export flag instead of -CreateCmdlet. When you do this and select an instruction, you are prompted for the name of a ZIP file. The instruction will be exported and saved to the specified file
Creating cmdlets directly from an instruction
If you know the name of the instruction in Tachyon, you can create a cmdlet directly from it without invoking the search. To do this as in the above example, enter the following
new-tachyoncmdlet -Instruction 1E-Explorer-TachyonCore-LocalGroupMemberSummary -cmdlet Get-LocalAccounts
Auto-generated cmdlets and parameters
An auto-generated cmdlet has parameters generated based on the instruction invoked. Additionally to these parameters, five other fixed parameters are always added to an auto-generated cmdlet.
Parameter | Description |
|---|---|
-TargetScope <pattern> | Specifies the FQDN pattern match for the device target scope. If not specified, you are prompted to supply it when the cmdlet is run |
-TargetFqdns <array of FQDNS> | Allows an array of one or more FQDNs to be specified as the target set for the cmdlet. This parameter is mutually exclusive with the -TargetScope parameter |
-PromptDefaults | If specified, causes any instruction parameters which have default values to be prompted for, with the default auto-filled in. Normally if this flag is not specified, instruction parameters with defaults cause the instruction to be invoked with those defaults automatically. Only instruction parameters without defaults are prompted for, unless this option is set. |
-Drilldown | If specified, causes any aggregating instruction to be displayed at detail level instead of at aggregated level. |
-Whatif | Causes the underlying instruction to return a list of devices which would be the targets if the instruction were executed without this option |
Note
These parameters behave identically to the parameters specified for the interactive search command, search-tachyon
The -Drilldown parameter is not added to a cmdlet if the instruction is not an aggregating instruction
Sample auto-generated cmdlet
Here is what the auto-generated cmdlet discussed above looks like. It is a thin wrapper over a cmdlet 'invoke-instruction' which supports the dynamic execution of any existing Tachyon instruction. The invoke-instruction cmdlet is discussed in more detail below.
The cmdlet builder adds parameters as discussed above; the five fixed parameters and then a set of additional parameters which are dependent on the instruction being wrapped.
In the example here, the instruction has a single parameter, accountName, which does not have a specified default. Consequently the parameter is created as a mandatory parameter and must be supplied when the cmdlet is executed.
If the instruction had parameters with defaults, then the cmdlet parameters for these will be marked Mandatory=false and the default value for each parameter will be as specified in the instruction.
This means that when you invoke the cmdlet, you can then override any default parameter if you wish, or leave it unchanged and do not supply an override.
Note that the four fixed parameters are simply passed down to the invoke-instruction command along with the instruction-specific parameters.
function get-localaccounts
{
[CmdletBinding(SupportsShouldProcess=$true, DefaultParameterSetName='devices')]
Param(
[Parameter(Mandatory=$true, ParameterSetName='TargetScope')] [string]$TargetScope,
[Parameter(Mandatory=$true, ParameterSetName='TargetFqdns')] [string[]]$TargetFqdns,
[Parameter(Mandatory=$false)] [switch]$PromptDefaults = $false
,[Parameter(Mandatory=$false)] [switch]$Drilldown = $false,
[Parameter(Mandatory=$true)] [string] $accountName
)
$instruction = "1E-Explorer-TachyonCore-LocalGroupMemberSummary"
$arguments = @{}
if ($promptdefaults)
{
$arguments.Add("PromptDefaults",$true)
}
if ($drilldown)
{
$arguments.Add("Drilldown",$true)
}
if ($TargetScope -ne "")
{
$arguments.Add("TargetScope",$targetScope)
]
if ($TargetFqdns -ne $null)
{
$arguments.Add("TargetFqdns", $TargetFqdns)
}
if (-not $pscmdlet.ShouldProcess($instruction))
{
$arguments.Add("Whatif",$true)
}
return Invoke-TachyonInstruction $instruction @arguments -accountName $accountName
}
Export-ModuleMember -Function get-localaccounts
cmdlet instruction parameter type mapping
The auto-generated cmdlet will map the underlying property type in the instruction as follows, where the left side is the type of the parameter as defined in the instruction and the right side is the PowerShell data type to which it maps:
string -> [string]
int -> [int]
float -> [double]
date -> [string]
time -> [string]
Constrained type values
Instruction properties whose type is set to 'value picker' will have a constraint added to the cmdlet using the PowerShell ValidateSet option. This will constrain the parameter in PowerShell to the list of valid values which the instruction has defined for the value picker.
Note
If you change the instruction parameters by uploading a modified version of it to Tachyon, don't forget to regenerate the cmdlet to keep it in sync.