PowerShell Executable Builder (PSEBuilder)

A modern, GUI-based PowerShell executable builder that creates standalone Windows executables from PowerShell scripts with embedded resources, custom icons, and professional metadata.

---

🚀 Key Features

• ✅ Modern WPF GUI: Easy-to-use graphical interface for building executables
• ✅ Professional Dark Theme: Eye-friendly dark mode with blue accent colors following Microsoft Fluent Design
• ✅ PowerShell 7+ Support: Automatic detection - prefers pwsh.exe (PS7+), falls back to powershell.exe (PS5.1)
• ✅ Zero Dependencies: Works on any Windows machine with PowerShell 3.0+ and .NET Framework 4.0+
• ✅ Multi-Resource Embedding: Scripts, images, configs, data files - all in one executable
• ✅ Automatic Image Conversion: JPG/PNG → ICO conversion built-in
• ✅ Professional Metadata: Company, version, copyright, description in exe properties
• ✅ Icon Support: Embed custom icons for professional appearance
• ✅ Memory Safe: No file locks, proper disposal, no memory leaks
• ✅ Security Hardened: Input validation, resource size limits, injection-proof
• ✅ No Assembly Loading: Direct csc.exe compilation prevents file locking issues

---

📸 Screenshot

Modern dark-themed WPF interface with tabs for configuration and asset management

---

🔧 Requirements

Built-in Windows Components (No Installation Needed):

• Windows 7+ with PowerShell 3.0+
• .NET Framework 4.0+ (included with Windows)
• That's it! No Visual Studio, no external packages, no complicated setup!

---

📖 Quick Start

Step 1: Launch the GUI

.\PSEBuilder.ps1

Step 2: Configure Your Executable

1. Basic Configuration Tab:

   • Select your main PowerShell script (.ps1)
   • Set executable name, version, description, company, copyright
   • Choose icon file (optional - supports .ico, .jpg, .png, .bmp)
   • Configure execution options (admin rights, window visibility, timeout)
   • Select output location for your .exe file

2. Assets Tab:

   • Add any additional files: images, configs, certificates, data files
   • All files will be embedded and accessible at runtime

Step 3: Build

• Click "Build Executable" button
• Wait for compilation to complete
• Your executable is ready!

Step 4: Use Your Executable

MyTool.exe

That's it! Everything is embedded in a single .exe file.

---

🎯 How It Works

Build Process

1. Resource Embedding: Files are Base64-encoded and embedded into C# code
2. Direct Compilation: Uses csc.exe directly (no Add-Type assembly loading)
3. Runtime Extraction: C# wrapper extracts resources to temp directory
4. PowerShell Detection: Automatically searches for pwsh.exe (PowerShell 7+) first, then powershell.exe (PowerShell 5.1)
5. PowerShell Execution: Launches detected PowerShell version with your script
6. Automatic Cleanup: Temp files cleaned up after execution

Resource Access in Your Scripts

PSEBuilder automatically provides the Get-ResourcePath helper function:

# In your PowerShell script:
$imagePath = Get-ResourcePath "logo.png"
$configPath = Get-ResourcePath "config.json"

# Use the files normally
$config = Get-Content $configPath | ConvertFrom-Json
$image = [System.Drawing.Image]::FromFile($imagePath)

See RESOURCE-ACCESS-GUIDE.md for details.

---

💡 Example: Building a GUI App with Resources

1. Create your PowerShell GUI script (my-app.ps1):

Add-Type -AssemblyName PresentationFramework

# Access embedded resources
$logoPath = Get-ResourcePath "logo.png"
$configPath = Get-ResourcePath "config.json"

# Build your WPF GUI...
$window = New-Object System.Windows.Window
$window.Title = "My App"
# ... rest of your GUI code
$window.ShowDialog()

2. Launch PSEBuilder:

.\PSEBuilder.ps1

3. In the GUI:

• Browse to my-app.ps1
• Set Name: "My Application"
• Set Version: "1.0.0"
• Add icon: logo.ico (or logo.png - auto-converted!)
• Go to Assets tab → Add Files: logo.png, config.json
• Set output path: MyApp.exe
• Click Build Executable

4. Distribute:

• Single file: MyApp.exe
• No dependencies, no installation
• All resources embedded

See examples/test-gui-app.ps1 for a complete working example.

---

⚙️ Configuration Options

Basic Configuration Tab

| Setting | Description | Example | |---------|-------------|---------| | Main Script | Primary PowerShell script to execute | scripts/main.ps1 | | Name | Application name | "My PowerShell Tool" | | Version | Semantic version | "1.0.0" | | Description | App description | "Custom PowerShell executable" | | Company | Company name | "Your Company" | | Copyright | Copyright year | "2025" | | Icon File | Icon for exe (auto-converts images) | icon.ico or icon.jpg |

Execution Options

| Option | Description | Default | |--------|-------------|---------| | Require Administrator | Force UAC elevation | Unchecked | | Show PowerShell Window | Visible console | Unchecked | | Timeout | Max execution time (minutes) | 5 | | Execution Policy | PowerShell execution policy | Bypass | | Working Directory | Script working directory | %TEMP% |

Assets Tab

Add any files to embed:

• Images: PNG, JPG, GIF, BMP
• Configs: JSON, XML, INI, CFG
• Certificates: PFX, CER, CRT
• Data: TXT, CSV, any file type
• Size Limit: 100MB per file

---

🔒 Security Features

Input Validation

• ✅ Resource size limits (100MB per file)
• ✅ Filename validation (no path traversal)
• ✅ Timeout range validation (1-1440 minutes)
• ✅ Version format validation

Compilation Security

• ✅ Injection-proof string escaping (handles all special characters)
• ✅ Resource key validation (alphanumeric + safe chars only)
• ✅ No code execution during build
• ✅ Separate process compilation (csc.exe)

Runtime Security

• ✅ Temp directory isolation
• ✅ Automatic cleanup on exit
• ✅ Optional admin elevation
• ✅ Execution policy enforcement

---

🚫 Limitations & Considerations

Current Limitations

• Windows-only: Requires Windows PowerShell and .NET Framework
• File Icon Only: Taskbar shows PowerShell icon (limitation of C# → PowerShell.exe architecture)
• Temp File Storage: Resources extracted to temp directory at runtime
• No Digital Signing: You must sign the exe separately if needed

Best Practices

• Test your script standalone before building
• Keep resource files under 50MB for best performance
• Use relative paths in your scripts
• Don't hardcode absolute paths
• Test built exe on clean systems

---

🆚 Comparison with Similar Tools

| Feature | PSEBuilder | PS2EXE | PowerChell | Other GUI Tools | |---------|-----------|---------|------------|-----------------| | GUI Interface | ✅ Modern WPF + Dark Theme | ❌ CLI Only | ❌ CLI Only | ⚠️ Various | | PowerShell 7+ Support | ✅ Auto-Detect | ⚠️ Limited | ❌ No | ⚠️ Unknown | | Multi-File Resources | ✅ Yes | ❌ Single Script | ⚠️ Limited | ⚠️ Varies | | Image → Icon Conversion | ✅ Automatic | ❌ No | ❌ No | ⚠️ Rarely | | Assembly Metadata | ✅ Full Support | ⚠️ Basic | ⚠️ Basic | ⚠️ Varies | | No File Locking | ✅ csc.exe Direct | ❌ Locks | ❌ Locks | ⚠️ Varies | | Memory Safe | ✅ Try-Finally | ⚠️ Basic | ⚠️ Basic | ⚠️ Unknown | | Dependencies | ✅ None | ✅ None | ✅ None | ⚠️ May Require | | Security Hardened | ✅ Yes | ⚠️ Basic | ⚠️ Basic | ⚠️ Unknown | | Professional UI | ✅ Dark Theme | ❌ N/A | ❌ N/A | ⚠️ Varies |

---

📁 Project Structure

Powershell_CPP/
├── PSEBuilder.ps1              # Main GUI application
├── examples/
│   ├── test-gui-app.ps1       # Example WPF GUI app with resources
│   ├── test.txt               # Example text file
│   └── image.png              # Example image file
├── docs/
│   ├── RESOURCE-ACCESS-GUIDE.md   # How to access embedded resources
│   ├── USAGE-GUIDE.md            # Detailed usage guide
│   ├── COMPREHENSIVE-DOCUMENTATION.md  # Complete reference
│   └── PowerShell-GUI-Dark-Theme-Reference.md  # Dark theme documentation
└── README.md                  # This file

---

🐛 Troubleshooting

Build Issues

"C# compiler (csc.exe) not found"

• Install .NET Framework 4.0 or higher
• csc.exe should be in: C:\Windows\Microsoft.NET\Framework64\v4.0.30319\

"Compilation failed with exit code 1"

• Check debug log in Downloads\PSEBuilder-Debug-*.log
• Ensure your PowerShell script has no syntax errors
• Try running script standalone first

"File is locked" error

• Old issue - FIXED in latest version!
• Using csc.exe directly prevents file locking

Runtime Issues

"Resources not found in exe"

• Resources are extracted to $env:PS_RESOURCE_DIR
• Use Get-ResourcePath helper function
• Check Downloads\TestGUI-Runtime-*.log for debugging

"PowerShell icon shows in taskbar"

• This is a known limitation of the architecture
• File icon works correctly
• Taskbar icon shows PowerShell.exe (the actual running process)
• Workaround: Create a Windows shortcut (.lnk) with custom icon

---

🙏 Credits & Inspiration

This project was inspired by and builds upon ideas from:

Main Inspiration

• PS2EXE by MScholtes
  • The original and most popular PowerShell → EXE converter
  • Pioneered the concept of embedding PowerShell scripts in C# wrappers
  • PSEBuilder adds GUI, multi-resource support, and advanced features

Additional References