Skip to content
ScriptoForm Docs

Compile a ScriptoForm

One of the best features of a ScriptoForm is that it can be easily compiled into an executable format. This provides a convenient means of launching the script and obfuscating it from the user as well as hiding the underlying PowerShell console window giving it the appearance of a native Microsoft Windows Forms application.
Compiling the executable can be performed after building a new project with the New-SADScriptoFormProject function, which is included in the SmartAceDesigns.ScriptoFormTemplates Powershell module, and customizing it per your design requirements. The executable is built with the Microsoft .NET framework using the latest Microsoft .NET SDK and can be targeted to one or more of the following supported frameworks:
  • .NET 4.8.x (Legacy)
  • .NET 8.x (LTS-Legacy aka “Long Term Support (Legacy)”)
  • .NET 9.x (STS aka “Standard Term Support”)
  • .NET 10.x (LTS aka “Long Term Support”)

The client device used to run the compiled executable must have the matching .NET runtime installed in order to use it. You are responsible for ensuring your client devices have this installed based on the targeted framework(s) you compiling for:

Methods

Section titled “Methods”

You have two options available to compile your ScriptoForm into an executable format: the dotnet CLI which is installed as part of the SDK or the Build-SADScriptoFormExecutable function which is included with the SmartAceDesigns.ScriptoFormTemplates PowerShell module and abstracts the use the dotnet CLI commands.

dotnet

Section titled “dotnet”
  1. Open a PowerShell console and navigate to the “Build” subdirectory in your ScriptoForm Project directory.
  2. Run one or more of the following commands from within your “Build” subdirectory to target the specified .NET framework(s) you need:

    The option compiles the ScriptoForm using the Microsoft .NET 4.8.x framework. The output executable is placed in the “\Release\Legacy” subdirectory in your project directory. The output directory can be changed by modifying the -o argument.

    PowerShell
    dotnet publish -f net48 -v q -o "..\Release\Legacy"; dotnet clean -f net48 -v q

Build-SADScriptoFormExecutable

Section titled “Build-SADScriptoFormExecutable”

The SmartAceDesigns.ScriptoFormTemplates PowerShell module includes the Build-SADScriptoFormExecutable function to assist with compiling your ScriptoForm into an executable format. This is the recommended method to build your ScriptoForm executable.

  1. Open a PowerShell console and navigate to your ScriptoForm Project directory.
  2. Run one or more of the following commands from within the root of your ScriptoForm Project directory to target the specified .NET framework(s) you need:

    The option compiles the ScriptoForm using the Microsoft .NET 4.8.x framework. The output executable is placed in the “\Release\Legacy” subdirectory in your project directory. The output directory can be changed by using the optional -ReleaseFolder argument with the function call.

    PowerShell
    Build-SADScriptoFormExecutable -BuildTarget Legacy

For more information on the Build-SADScriptoFormExecutable function and available parameters: Get-Help Build-SADScriptoFormExecutable -Full

Deep Dive

Section titled “Deep Dive”
The following topics provide a more in-depth discussion of the compile and execution process.

Build files

Section titled “Build files”
When you build a new ScriptoForm from the New-SADScriptoFormProject function, the files needed to compile the executable are automatically included in project directory for you. This includes:
  • DirectoryBuild
    • Build.cs
    • Build.csproj
”Build.cs” is the C# source code file used to create the executable. This file will work “out-of-box” with your ScriptoForm project when built with the New-SADScriptoFormProject function - no modification is needed.
”Build.csproj” is the C# project file that contains instructions for building the executable. This includes the type of executable to build (“WinExe”), the supported .NET framework targets (“net48;net8.0-windows;net9.0-windows;net10.0-windows”), and embedded resource files (“Script.ps1”). The dotnet.exe CLI parses this file when building the executable to determine how to build it.

Execution Process

Section titled “Execution Process”
When the ScriptoForm executable is run it performs the following steps:
  1. The executable creates a temporary directory in the users “Temp” directory. By default, this is “C:\Users\username\AppData\Local\Temp” on the Windows computer. The name of the temporary directory created is a combination of the script name and a randomly generated GUID value (e.g. “Show-DemoForm-A92D3EAB-FB6C-4AE6-8580-77E4C24C24F8”). This allows mulitple instances of executable to be run at the same time, which each instance having its own unique extraction directory.
  2. The executable extracts the “Script.ps1” file, and any additional support files declared in the “Build.csproj” file, to the temporary directory.
  3. The executable launches that latest version of PowerShell detected on the system and not excluded with a command-line argument to the executable, based on a standard installation directory names, with “Script.ps1” as the “-File” argument.
  4. The user interacts with the ScriptoForm as designed.
  5. When the user closes the Form the PowerShell process exits.
  6. The executable deletes the temporary directory and all contents.
  7. The executable closes.

Command-line Arguments

Section titled “Command-line Arguments”

The following optional command-line arguments can be used with the compiled executable to control how a ScriptoForm launches at runtime:

ArgumentPurposeNotes
-exclude:allExclude PowerShell x.x.x versionsDo not use with other exclude arguments
-exclude:ps7Exclude PowerShell 7.x.x versionsDo not use with other exclude arguments
-debugShow console windowUse individually or with an exclude argument

Examples

Section titled “Examples”

Display the PowerShell console, typically for debugging purposes, along with the ScriptoForm form:

PowerShell
Show-DemoForm.exe -debug

Force the ScriptoForm to launch with Windows PowerShell 5.1:

PowerShell
Show-DemoForm.exe -exclude:all

Force the ScriptoForm to launch with Windows PowerShell 5.1 and show the console window:

PowerShell
Show-DemoForm.exe -exclude:all -debug

Exclude PowerShell 7 but allow (future) newer versions such as PowerShell 8:

PowerShell
Show-DemoForm.exe -exclude:ps7