Discovering Commands and Accessing Help

The GENESIS PowerShell interface installs many modules, each with dozens or hundreds of commands. Rather than memorizing them, you can discover what is available on your system and read built-in help for any command using standard PowerShell discovery commands. Use this routine whenever you need to find the right command or confirm a command's parameters before you run it.

To discover the available modules and commands:

1. List the installed GENESIS modules:

   Get-Module -ListAvailable -Name *Powershell

   Each GENESIS provider has its own module whose name ends in Powershell, such as IcoAssetCatalogPowershell or HHPowershell. See the PowerShell Module Reference for what each one configures.

2. List the commands in a module to see what it can configure:

   Get-Command -Module IcoAssetCatalogPowershell

   The result is the full set of Get, New, Set, and Remove commands for that provider's entities.

3. Narrow the list when a module is large by filtering on a verb or entity name:

   Get-Command -Module IcoTrgPowershell -Name New-*

   Filter on an entity instead of a verb—for example Get-Command -Name *Equipment*—to find every command that acts on a particular kind of entity across all modules.

To read help for a specific command:

1. Show the full help for a command, including every parameter, with Get-Help and the -Full switch:

   Get-Help New-TrgDataItem -Full

   The help lists each parameter with its type, whether it is mandatory, its position, and a short description. For a command whose name you know, this is the fastest way to learn exactly what it accepts.

2. Read the output to learn things you could not infer from the command name alone. The SYNTAX block and an individual parameter block from the example above look like this:

   SYNTAX New-TrgDataItem [-Name] <Object> [-ExecuteCondition {AnyChange | ChangeToTrue | ChangeToFalse | IsTrue | IsFalse | AnyValueChange}] [-Description <string>] [-UseDelay <bool>] [-Delay <int>] [-Severity <int>] [-ParentName <Object>] ... PARAMETERS -Name <Object> Enter the entity name, e.g. EntityName or the entity itself or the entity key Required? true Position? 0 -ExecuteCondition <TrgExecuteConditionType> Required? false Position? Named

   That short excerpt already gives you the following information you would otherwise have to guess at:

   • The valid values are enumerated.

     -ExecuteCondition accepts exactly AnyChange, ChangeToTrue, ChangeToFalse, IsTrue, IsFalse, or AnyValueChange. The help spells out the complete set, so you do not have to discover the accepted condition names by trial and error.

   • You learn what is required and how to pass it.

     -Name is Required? true at Position? 0, so you can supply it as the first argument without typing the parameter name. Its description reveals that it accepts a name, a key, or the entity itself—the flexible identification described in Entities, Keys, and the Command Model.

   • Optional parameters are bracketed.

     Everything contained in [ ] in the SYNTAX block is optional, so you can instantly see the minimum needed to run the command.

3. Request a smaller view when you do not need the full output:

   • Get-Help New-TrgDataItem -Detailed—parameter descriptions and examples, without the complete reference block.

   • Get-Help New-TrgDataItem -Parameter ExecuteCondition—help for a single named parameter.

   • Get-Help New-TrgDataItem -Examples—only the usage examples, where a command provides them.

4. Inspect the properties returned by an entity, which are also the values you can set, by reading one and listing its members:

   Get-TrgDataItems | Select-Object -First 1 | Get-Member -MemberType Property

   This shows the property names that you will see on a returned entity and that you can supply to the matching Set command.

Related Topics:

• Creating an Asset with PowerShell

• Finding and Updating a Trigger

• Entities, Keys, and the Command Model