PowerShell Studio: Passing and Returning Values using Forms

• PowerShell Studio
• Sample Script
• Windows PowerShell

User Rating: 3 / 5

Two frequent questions we get on the forums are:

How do I pass a value to another form?

How do I get the results from a form?

In this article, we will answer these common questions in order to give you a better understanding about how to use projects with multiple forms.

Getting Started

You will need to create a project with multiple forms in order to proceed. The Multi-Form Project template is a good starting point. At the end of this article there is a link to download a sample project that demonstrates how to use these techniques.

Calling Forms in a Project (Reference Functions)

Once you have a project with a form, you can call the form from the Startup.pfs or from another form. To do this, you must use the Form’s Reference Function. A file’s Reference Function uses the following naming convention:

Call-<File Name>_<Extension>

For example, to call the AddExtension.pff file in the sample project, you would use the following reference function:

Call-AddEmployeeForm_pff

Calling PS1 Files

If you need to call a ps1 file you will have to set the following project file’s properties in the Project Panel as follows:

By setting the CommandExtension property to False, you are telling the project to treat the ps1 file as a function. This allows you use the file’s reference function to execute it:

Call-MyScript_ps1

Note: You can still dot source ps1 files; but if you do you must set the ps1 file’s Build setting to Content so that it isn’t merged into the final project script.

If you are unsure of the Reference Function name, you can look at the Reference Name property of the project file:

In addition, PowerShell Studio’s PrimalSense will display a list of Reference Functions when you type “Call-” :

Passing Parameters

There are times when you need to pass information to a child form. In these situations, you can use a parameter block in the same manor you would with a traditional ps1 script. To do this, go to the form file’s  script section and insert a Parameter block at the very top of the script. It is very important that nothing but comments appear before the parameter block.

Once you add the parameter block, PowerShell Studio will color the parameters accordingly:

Note: Script scope variables can also be used as an alternative to parameters.

Returning Values

Now that you know how to pass values to a form, how do you get values back? Returning values depends on what you are referencing. For example, Form files are handled differently the ps1 files.

Form Return Values

The Form’s Reference Function returns the DialogResult of the Form when it is closed. How do you handle return values?

Luckily PowerShell Studio auto generates variable values with the values of controls in the form. The return variables name convention is as follows:

$<Form Name>_<Control Name>

For example, if AddEmployeeForm.pff has a TextBox named textBoxFirstName, PowerShell Studio will generate the following return variable:

$AddEmployeeForm_textboxFirstName

When you use a Reference Function, PowerShell Studio’s PrimalSense will automatically include the return variables when you type $.

The value contained in the variable depends on the control. The following is a list of controls that generate return values:

Returning Custom Values in Forms

In the case where the control doesn’t return a value or you want to return a custom value / object, you can create a variable using the script scope:

$script:MyReturnValue = ...

Then you can reference the variable in the file that called the form.

if(Call-AddEmployeeForm_pff) –eq 'OK')
{
    Out-Default $script:MyReturnValue
}

In the sample project, the amount of time the user took to complete the Add Employee form is saved in a script variable. The main form then displays a message if the user took longer than the allotted time.

Script Return Values

Script (ps1) files simply return the objects via the pipeline as there is no form to return a DialogResult.

Call-MyScript_ps1 | Out-Default

Hopefully now you have the tools to create complex GUIs that utilize multiple forms. The sample project below utilizes the techniques covered by this article.

Sample Project – Employee Roster

The Employee Roster is a sample project that uses a grid to display a list of employees. When you press a button, a second form is displayed to collect employee information and the results are in turn loaded into the grid of the first form.

  - Employee Roster Sample Project

• Prev
• Next