PowerShell Studio Projects: Introduction

Using the project functionality in PowerShell Studio makes it easier to manage multi-file scripts, create multi-form GUIs, and create script modules.

To create a new project in PowerShell Studio, open the File menu, select the New tab, then select Project:

The types of PowerShell Studio projects:

  • Collection
  • Form
  • Module
    • From Existing Module
    • From Functions
    • From Help File
    • New
  • Multi-Form
  • Windows Service Project
  • Empty

After selecting a project template, you will be prompted for additional information to create the project.

The prompted information includes:

  • Project Name – The name of the project.
  • Project Folder – The directory where the project will be located.
  • Create project folder – Creates a folder with the project name in the Projects folder.
  • Include Git ignore file for temporary project files – Creates a .gitignore file.

The File menu will close, and you may be prompted for additional information depending on the selected project template. Next, the Project panel will open with the newly created project:

A project file has the file extension of PSPROJ. Additionally, a file with the extension PSPROJS is created, containing the project’s current state (e.g., what files are open).

General Project File Settings

All build settings for project files can be viewed in the Properties panel when the file is selected in the Project panel:

File Path is the location where the file is stored. This is not an editable property.

Name is the name of the file, which can be edited here.

Reference Function is the name of the function that invokes the project file.

Shared allows the functions and variables declared in the ps1 file to be referenced by other project files; if Shared is enabled, you will not be able to invoke the file by its reference function. Setting the Shared property of a project file tells PowerShell Studio to provide PrimalSense for the functions defined in the file, across the whole project.

Build Order allows you to determine the order in which project files are merged into the final project script. This setting only applies to project files with the Build property set to Include. Three options are supported:

Include – The file is included in the build. The Reference Function properties are used to help integrate the file contents into the shell.

Exclude – The file will not be included in the build.

Content – The file will be included in the build but any code contained in the file will not be integrated into the shell. This is a useful option when you want to include data files in your project.

The Build Order can be important when the content of one project file is dependent on the content of another file.  For example, when dealing with class inheritance in PowerShell, you must make sure the base class is defined before declaring any classes that inherit from that base class. By setting the build order of the individual class files, you can ensure that the final script includes the base class definition before the inherited class definition.

Another use case would be when functions or global variables are defined within a global file (Shared = True). To ensure those declarations are defined before invoking, the build order index should be set to a value lower than that of the dependent project files.

Set the build order of project files by modifying the zero-based index of each project file. An index of 0 ensures that the file will be the first one merged into the generated script.

There are some exceptions to the build order. In a module project, the primary psm1 file’s content is included at the end of the generated script regardless of its Build Order property value. Collection projects only support project files with Build = Content, therefore the Build Order property is not applicable.

General Project Settings

General project settings can be viewed in the Properties panel when the Project name is selected in the Project panel:

Project Name is the name of the project.

Project Path is the path to the project file (PSProj) file.

Synchronized will synchronize the project files and folders. When the project is loaded, PowerShell Studio will automatically add new files and remove any missing files.

File Filter determines which files to search for when synchronizing the project files. Edit this property to customize the files that are included in the synchronization.

The File Filter Formatting looks like the following:

*.extension1;*.extension2

Each extension filter needs to be separated by a semi-colon. For example, you can include images by appending the following filters:

*.jpg;*.png;

The default filter includes all PowerShell file extensions.

Other Settings

From Options, there are two additional project settings (Options > General > Project Settings):

Default action for copy import file to project determines whether the application will prompt when existing files are attempting to be added to a project:

Sync files when the application is activated allows you to trigger project file synchronization when the application regains focus (activated).

In order for this feature to work, you must have a project opened with file synchronization enabled (Synchronized = True):

This option ensures that the application can detect changes when you are making modifications to the project’s folder structure outside of PowerShell Studio.

When changes are detected upon opening the file, messages will be written to the Output pane:

The synchronization messages use + and  to represent the adding and removing of files.

Additional Files

Depending on the project template, your project may include one or both of the following files: Global.ps1 and Startup.pss

Global.ps1 is merged with all project files with the build setting set to include into one script file (ProjectName.Run.ps1). The file Shared property is always set to True.

Startup.pss is used to initialize or create anything to start your script.

Exporting to a PS1

On the ribbon under the Deploy tab is a section called Export:

Depending on the type of project, a project can be exported to a file (e.g., ProjectName.export.ps1), or the exported text can be copied to the clipboard. This does not apply to a module or collection project as neither build into a single PS1 script.

When a project is exported, all the files with the build setting of Include will be added to a ps1 file. The order in which the files are added will depend on their build order.

The resulting PS1 file will be broken up into regions based on the files included in the project. The region will contain the file name written like the following:

#region Source: FileName.ps1

An exported project with multiple files would look similar to this when all regions are collapsed:

PSF files are broken down further during the export process. For more information on how a PSF file is converted to a PS1, please refer to the following article: Basics: Working with a PSF file in PowerShell Studio – SAPIEN Blog

It is important to note that when you run or package a project, this export process is done for you. When you run (Ctrl + F5) or debug (F5), a project is exported to a PS1 called ProjectName.Run.ps1. When packaging a project to an executable, the file is exported to a PS1 called ProjectName.Package.ps1.

Recovery

When recovering a project, the project is recreated based on the recovery data.

To revert the exported PS1 file back to a project, 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:

  1. Search for the original project file.
  2. Recover the project file from the recovery data.

You can set how PowerShell Studio will prompt in Options (Options > Designer > Source Files):

The default values for both settings are to Ask.

When an exported project 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 project 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.

It is important to note that the files recovered are the files that were combined into a single PS1 file. Any file with the Build set to Content will not be recovered.

Related

Feedback

All information provided in this article is based on the functionality available in PowerShell Studio 2022 build 5.8.202.

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.