Why Breaking Changes?
In PowerShell Studio 5.3.130, we made some changes to projects that aren’t recognized by previous versions of PowerShell Studio. This blog post describes the changes, explains why we made them, and offers a workaround in case you really need it.
Also, note that SAPIEN has properly incremented the Minor property in the PowerShell Studio version number to 3 to indicate a breaking change. We went from 5.2.129 to 5.3.130.
If you created a project in an older version of PowerShell Studio, PowerShell 5.3.130 and later will open and update your project. But, if you create or open a project in 5.3.130 (or later), earlier versions of PowerShell Studio can’t open the project.
This is because we introduced some breaking changes. We don’t do this without serious reflection, but we also don’t want to be tied forever to outdated or inefficient practices. And, we made sure that if you were really stuck, you could revert the changes so that the older version could open the project.
Actually, two things changed:
- Project Files: We changed the .psproj file to be more accurate and flexible. This gives us room to improve and extend features of our projects in the future without further breaking changes. This change applies only to PowerShell Studio projects.
- Approved verbs: We have also changed the verbs that we use in reference functions from Call, which was unique and easy to find, but unapproved, to Show for GUI form reference functions and Invoke for scripts included in modules. As a result, Script Analyzer does not report a warning and Import-Module does not warn the user about functions with unapproved verbs.TIP: Need information about approved verbs in PowerShell? See Get-Verb and Approved Verbs for Windows PowerShell Commands.When you create GUI forms, PowerShell Studio wraps each form in a reference function, so you can easily open the form and pass data to it from other forms. You won’t see this function in your .psf file, but you can see it in the export file that PowerShell Studio creates for your form (Click Deploy and then Export to File or Export to Clipboard.Previous versions of PowerShell Studio would name the form reference function Call-<FormName>_psf, such as Call-MainForm_psf. PowerShell Studio version 5.3.130 and later name the form reference function Show-<FormName>_psf, such as Show-Mainform_psf.
PowerShell Studio also creates reference functions for script files (.ps1) that you include in a module file (.psm1) that is part of a PowerShell Studio project. Specifically, these are script files that have a Build value of Include and a Shared value of False. To see the properties of each file in a project, use the Properties pane.
For example, here is the Properties pane for a Get-Profile.Tests.ps1 file in a module project.
When you build a module from the project, PowerShell Studio wraps the content of the (.ps1) script file in a reference function and adds it to the (.psm1) module file. This makes it very easy to call the script contents in the module and to pass data to it as parameters.
Previous versions of PowerShell Studio would name the script reference function Call-<ScriptName>_ps1, such as Call-Get-Profile_Tests_ps1. PowerShell Studio version 5.3.130 and later name the form reference function Invoke-<ScriptName>_ps1, such as Invoke-Get-Profile_Tests_ps1.
What Breaks in this Breaking Change?
When you open a project that was created in an older version of PowerShell Studio, PowerShell Studio 5.3.130 or later opens and updates the project, including the XML and any reference function names. You can then work on the project in the standard way. No breaks in this scenario.
However, if you open a project that was updated or created by PowerShell Studio 5.3.130 or later in an older version of PowerShell Studio, the older version cannot parse the new project file XML. Instead, it displays the following message in the Output pane:
Unable to load <ProjectName>.psproj (Project Format: v2.0), because it was created with a different version of PowerShell Studio.
Export.ps1 files are not affected by the breaking change, even though they use the new verbs. If you have an Export.ps1 file for a GUI application that was created in any version of PowerShell Studio, PowerShell Studio 5.3.130 and later can open it and can recreate the original PowerShell GUI form file (.psf) from the Export.ps1 file. And, older versions of PowerShell Studio can open Export.ps1 files that were created in PowerShell 5.3.130 and later and recreate the forms files (.psf) that are defined in the Export.ps1.
However, when Export.ps1 files are created for a form or multi-form project, older versions of PowerShell Studio (before 5.3.x) cannot recreate the forms because they cannot read the project file (.psproj).
TIP: An Export.ps1 file is a PowerShell script that contains all code for a PowerShell GUI application, including the code in the .psf file that you create. These files are generated dynamically when you run or debug your .psf file. Unlike .psf files, which are specific to PowerShell Studio, you can run the Export.ps1 file on any system that has PowerShell. To create an Export.ps1 file for your .psf file, click Deploy and then click Export to File or Export to Clipboard.
Workaround: Psproj.bak file
When you open an older project in PowerShell Studio 5.3.130 or later, PowerShell Studio updates the XML in the .psproj file and updates the reference function verbs in the project. But, it also saves the original .psproj file in a .psproj.bak file. If you must open a newer project in an older version of PowerShell Studio, you can rename the current .psproj file to something else, such as .psproj.new, and rename the .psproj.bak file to .psproj. Then, you can open the project in the older version of PowerShell Studio.
To revert the function name, right-click the function name, click Call Project File, and select the form that you want to open.
While we try to prevent incompatibility at all levels, we don’t want it to hinder progress or tie users to old standards that conflict with best practices. As always, to make an omelet, you have to break a few eggs.