PSF files are PowerShell Studio’s Windows Forms (WinForms) files (PowerShell Studio Form). This file contains all the designer and script information in an xml format. Most code in a PSF file should be an event or function. Any code not in an event or function will run first when the PSF file is exported to a ps1 file.
When opened in PowerShell Studio, the file is split into two parts, Designer and Script:
PSF files open from the last known state; if you had the Designer open when you saved the file, then the Designer tab will be selected the next time the file is opened. The same is true for the Script tab.
When the Designer tab is open, the Properties pane will become enabled and show the properties for the selected controls on the Designer surface:
When the PSF file’s Designer tab is open, the ribbon will also switch to the Designer tab:
From this ribbon tab, you can align, position, and resize selected controls.
You can navigate the Forms’ controls from the dropdown box on the Properties pane:
The Forms’ controls are listed, and can be selected, from the Toolbox pane’s Select tab:
For more on working with the Designer, the following references will have more information:
- Basics: How to add an Event Handler in PowerShell Studio – SAPIEN Blog
- Basics: Copying Controls and Events in the Designer – SAPIEN Blog
- Property Pane: Change property values of multiple objects – SAPIEN Blog
- GUI Designer – SAPIEN PowerShell Studio Manual
PSF files also provide support for adding references to assemblies. When the Script tab is open, you can add assemblies from the ribbon (Home->Edit):
This will open the Assemblies dialog with all the current referenced assemblies listed:
Clicking to add a new assembly will open an additional dialog that will load all assemblies on your machine from the default location in Windows:
By default, references to System.Windows.Forms and System.Drawing will always be added on export to a PS1.
Exporting a PSF to a PS1
On the ribbon under the Deploy tab is a section called Export:
A PSF file can be exported to a file (e.g., FileName.export.ps1), or the exported text can be copied to the clipboard.
When a form is exported, all form code is encased in a function called Show_FileName_psf. All form-related code exists in this function. To view the form, simply call the function.
This function is broken into sections:
- Assemblies – All references to assemblies.
- Generated Form Objects – All Forms’ controls and associated objects being initialized.
- User Generated Script – All code from the Script tab.
- Generated Events – These are event handlers for loading the window state of the form and for cleanup when the form closes.
- Generated Form Code – All properties and events of the Forms’ controls and objects being set.
It is important to note that when you run or package a PSF file, this export process is done for you. When you run (Ctrl + F5) or debug (F5), a PSF file is exported to a PS1 called FileName.Run.ps1. When packaging a PSF to an executable, the file is exported to a PS1 called FileName.Package.ps1.
How does this affect you?
If you are working from a single PSF file, this will have little effect on the finished PS1 file. However, for people using a project, it is important to understand that you will not be able to call any of the GUI controls generated from anywhere except the corresponding PSF file. The is because of scoping rules. For more information on scope, please read the following articles:
- Scope in a PowerShell GUI App – SAPIEN Blog
- First rule of PowerShell scoping rules… – SAPIEN Blog
- PowerShell Scoping – Revisited – SAPIEN Blog
This also means that if there is any code that needs to run before the creation of the form, a form project should be used instead of a single PSF file. This is because a form project comes with an additional project-specific file called a Startup.pss.
When recovering a PSF file, the form is recreated based on the recovery data. This means any manual changes made to the generated form code will not be recovered.
To revert the exported PS1 file back to a PSF file, the exported file must have the recovery data. This setting can be selected in Options (Options->Designer->Export):
When an exported PS1 file is opened in PowerShell Studio, it can prompt for two things:
- Search for the original PSF file.
- Recover the PSF file from the recovery data.
How PowerShell Studio will prompt can be set in Options (Options->Designer->Source Files):
The default values for both settings are to Ask.
When an exported PS1 file is opened in PowerShell Studio, if it is able to find the source file, it will prompt to load the original file:
If it is unable to locate the source file in the current directory, it will prompt to search for the source file:
If the original source file cannot be found or the original PSF file is not loaded, it will ask to reconstruct the file if the file contains recovery data:
This process will vary depending on the settings in Options.
As always, any feedback is appreciated. If you have a particular type of blog article or product feature request you would like to see, please submit your suggestions on the Wish List and Feature Requests forum or the new Feature Requests page.