PowerShell Studio: Custom PrimalSense
- Written by David Corrales
- Last Updated: 13 June 2016
- Created: 15 March 2016
- Hits: 6731
Custom PrimalSense Lists
The customizable PrimalSense feature allows users to tailor their PrimalSense experience. The contents of the custom PrimalSense can be derived from a static list or from a dynamically created list using a PowerShell script.
These custom PrimalSense lists can be triggered via a shortcut name, similar to snippet shortcuts. For example, if you type the following shortcut:
To display the custom PrimalSense list, press [Ctrl + Alt + P] or [TAB].
The shortcut will be replaced with the selected item in the PrimalSense list.
In addition, custom PrimalSense lists can be triggered by typing a particular cmdlet / parameter combination or a specific parameter regardless of command.
The custom list in this case is triggered when the user presses [SPACE] after typing the Name parameter of Get-Process.
Let’s look at the types of lists in more detail.
Static lists are the simplest method for creating a custom PrimalSense list. These lists are simply read from a static data file source, such as a CSV file, when the list is triggered. Let’s look at the supported data file formats.
Data File Formats
There are two supported data file formats: CSV and XML files.
The CSV is the simplest format. It can consist of simple list where there can only be one list item per line.
For example, GetProcess_Name.csv data file contains the following:
Note: Since this is a CSV file format, you must escape double quotes using another double quote “”.
You have the option to associate each item with a pre-defined picture (via index) and a value using the following format:
Name, Index, Value
- Name – This is the text displayed in the PrimalSense list.
- Index – (Optional) The numeric index of the image you that will be displayed next to the name in the PrimalSense list. Use –1 if you do not wish to associate an image. See below for a list of image indexes.
- Value – (Optional) The value that is inserted into the editor when the item is selected from the PrimalSense list.
Here is an example csv that uses images and values:
The resulting PrimalSense list:
The inserted value:
The following table contains the list of supported image indexes:
|41||Last Edit Position|
The second supported data format is XML. Use the XML file format to insert more complex values, such as a multiple line script.
The XML file consists of a root element named List, which contains a child element for each item named Item.
The item element contains the following attributes:
- name – contains the display name of the item in the PrimalSense list.
- image – contains the image index of the item.
A CDATA block contains the multi-line text that is inserted when the item is selected in the PrimalSense list.
For example, the functions shortcut triggers the following list of functions:
When an item is selected, a complete function is inserted:
For the cases where a static list isn’t enough, PowerShell Studio gives you the option to dynamically create the data file before displaying it in the PrimalSense list. This is accomplished, by running a custom PowerShell script that generates the necessary data file. Next, we will look at how to configure triggers and create scripts that generate dynamic lists.
The custom PrimalSense list triggers are stored in the following XML file:
C:\ProgramData\SAPIEN\PowerShell Studio 2016\CustomSense\Triggers.xml
The XML file is made up of a Triggers root element and each individual list trigger is defined by a child element named Trigger.
Each Trigger element has the following attributes:
- shortcut – (Optional) The shortcut name that triggers the custom PrimalSense list when the user presses [Ctrl + Alt + P]. The shortcut must not contain spaces.
- command – (Optional) The command/cmdlet that the trigger is bound to. Use an asterisk * to denote all commands. This field requires the parameter attribute.
- parameter – (Optional) The parameter that triggers the custom PrimalSense list. This field requires the command attribute.
- type – [cached|dynamic] (Default: cached) Determines if the list is cached in memory or is read every time the list is triggered.
- datafile – (Required) Specifies the data file that is to be loaded (CSV or XML).
- elevated – (Optional) (Default: False) Determines if the script needs to be elevated.
- timeout – How long PowerShell Studio should wait for the process to complete before quitting.
- autoquote – [True|False] (Default: True) If set to True, PowerShell Studio will automatically wrap quotes around the values contained in a CSV file when necessary.
- scriptfile – Specifies the script to run in order to create the data file.
Note: If you modify the Triggers.xml file, you will need to reload PowerShell Studio in order for the changes to take effect.
When you specify a script file in the triggers XML file, PowerShell Studio will execute said script when the list is triggered.
Let us look at the contents of the sample GetProcess_Names.ps1 script:
Get-Process | Select-Object -ExpandProperty Name -Unique > "$CustomSensePath\GetProcess_Name.csv"
The script simply pipes out the results of Get-Process to a basic csv file. Notice the $CustomSensePath variable, this is a special variable that contains path information. You can utilize the following variables in your script:
This variable contains the path to the CustomSense folder. For example:
C:\ProgramData\SAPIEN\PowerShell Studio 2016\CustomSense\
Note: The data file must be located in the same folder as the triggers.xml.
This variable contains the file path to the active script in PowerShell Studio. This value will be empty for new unsaved files.
You should now have a better understanding of how to use PowerShell Studio’s Custom PrimalSense feature. This feature is another tool you can use to tailor PowerShell Studio to fit your specific needs.
If you have any comments or feedback, please feel free to post in our PowerShell Studio product forum.