ps2exe Documentation

Win-PS2EXE provides a graphical interface for the PS2EXE compiler with the following characteristics:

Features:

• WPF application that compiles without Visual Studio or MSBuild.
• Compatible with Windows machines running .NET 4.x.
• Supports drag-and-drop for file names.

Restrictions:

• Only supports a single source file per compilation.

When a script is converted to an executable, some standard PowerShell variables behave differently:

1. $PSScriptRoot: This variable is empty in a compiled executable. Use $ScriptRoot instead, or use the following compatibility pattern:

   if (!$PSScriptRoot) { $PSScriptRoot = $ScriptRoot }

2. $MyInvocation: This variable is set to different values than in a standard script.
3. Parameter Types: All parameters passed to the executable are treated as STRING. If your script expects other types, you must perform explicit conversion.

When generating examples, the compilation method depends on the filename:

• GUI Examples: Files containing -GUI in their name are compiled using the -NoConsole flag (hiding the console window).
• Console Examples: Files without -GUI in their name are compiled as standard console applications.

Use the -embedFiles parameter with a hashtable to include external files inside your executable. At runtime, these files are extracted to the specified target paths.

• Target Paths: Use '.\' for paths relative to the executable. Use environment variables like %TEMP% or %APPDATA% (they are expanded at runtime).
• Uniqueness: Source file names must be unique.
• Failure Behavior: If a file cannot be created at the target path, the executable will stop immediately.

Use Invoke-ps2exe or the ps2exe alias to compile a .ps1 script into a Windows executable (.exe). If the output file path is omitted, the executable will be created in the same directory as the source script with the same name but a .exe extension.

You can also launch Win-PS2EXE to use a graphical user interface for the conversion process.

To generate the available examples for PS2EXE using the Windows Command Prompt (CMD), run the batch file:

.\BuildExamples.bat

Win-PS2EXE is a WPF-based graphical front end for the PS2EXE module, allowing you to compile PowerShell scripts into Windows executables without needing Visual Studio or MSBuild. It requires .NET 4.x and works on any Windows machine.

To use Win-PS2EXE:

1. Install the required PS2EXE PowerShell module.
2. Launch the application by typing Win-PS2EXE in a PowerShell console.
3. Fill in the fields in the GUI (the Source file field is the only mandatory one).
4. Click Compile. A PowerShell window will open to perform the compilation process.

When using -noConsole mode, PowerShell commandlets that output multiple lines (like dir) will trigger a separate GUI message box for every single line of output. To prevent this, pipe your command to Out-String to consolidate the output into a single string/message box.

dir C:\ | Out-String

You can install the ps2exe module via the PowerShell Gallery using Install-Module. Alternatively, you can download it manually from the PowerShell Gallery website.

Install-Module ps2exe

To generate the available examples for PS2EXE, run the build script from your terminal. Depending on your shell, use one of the following commands:

• PowerShell: `.\

.\BuildExamples.ps1

Compiled executables are not secure containers for secrets. Anyone can use the -extract parameter to retrieve the original PowerShell script in clear text.

Example of extraction:

Output.exe -extract:C:\Output.ps1