DevPossible.PwshBuildEvents 1.1.0

DevPossible.PwshBuildEvents

A lightweight NuGet package that enables PowerShell Core (pwsh.exe) pre-build and post-build scripts for .NET projects.

Overview

This package automatically hooks into the MSBuild process to execute PowerShell scripts located in your project's Properties folder:

• Properties/prebuild.ps1 - Executed before compilation
• Properties/postbuild.ps1 - Executed after successful compilation

Key Features:

• Sample scripts included - Template scripts are added to your project on install
• Zero configuration required - just customize the scripts
• Clean install/uninstall - no modifications to your project file
• Non-invasive - works alongside existing <PreBuildEvent> and <PostBuildEvent> targets
• 37 MSBuild properties available via environment variables (same as VS build event macros)

Installation

dotnet add package DevPossible.PwshBuildEvents

On installation, sample scripts are added to your Properties/ folder:

• Properties/prebuild.ps1 - Template for pre-build tasks
• Properties/postbuild.ps1 - Template for post-build tasks

Note: These files remain in your project if you uninstall the package - delete them manually if not needed.

Usage

Quick Start

The sample scripts are ready to use. Just customize them with your build logic:

Properties/prebuild.ps1

# Build properties are available via environment variables (prefixed with MBLD_)
$ProjectDir      = $env:MBLD_PROJECT_DIR
$ProjectName     = $env:MBLD_PROJECT_NAME
$Configuration   = $env:MBLD_CONFIGURATION
$TargetFramework = $env:MBLD_TARGET_FRAMEWORK

Write-Host "Running pre-build for $ProjectName ($Configuration)"
# Your pre-build logic here

Properties/postbuild.ps1

# Build properties are available via environment variables (prefixed with MBLD_)
$ProjectDir      = $env:MBLD_PROJECT_DIR
$ProjectName     = $env:MBLD_PROJECT_NAME
$Configuration   = $env:MBLD_CONFIGURATION
$TargetFramework = $env:MBLD_TARGET_FRAMEWORK
$TargetDir       = $env:MBLD_TARGET_DIR
$TargetPath      = $env:MBLD_TARGET_PATH

Write-Host "Running post-build for $ProjectName ($Configuration)"
# Your post-build logic here

2. Build your project

The scripts execute automatically during dotnet build:

dotnet build

Output:

Running pre-build for MyProject (Debug)
  MyProject -> C:\Projects\MyProject\bin\Debug\net8.0\MyProject.dll
Running post-build for MyProject (Debug)

Available Environment Variables

All MSBuild properties are passed to your scripts via environment variables (prefixed with MBLD_). This mirrors the macros available in Visual Studio's built-in build events.

Project Information

Build Configuration

Output Paths

Solution Information

Versioning

Note: Variables containing semicolons (like DefineConstants and TargetFrameworks) are automatically converted to comma-separated values.

MSBuild Macro Comparison

If you're migrating from Visual Studio's built-in build events, here's how the macros map:

Common Examples

Copy output to a shared folder (postbuild.ps1)

$destination = "\\server\builds\$env:MBLD_PROJECT_NAME\$env:MBLD_CONFIGURATION"
if (-not (Test-Path $destination)) {
    New-Item -ItemType Directory -Path $destination -Force | Out-Null
}
Copy-Item $env:MBLD_TARGET_PATH -Destination $destination -Force
Write-Host "Copied to $destination"

Generate build info file (prebuild.ps1)

$buildInfo = @{
    BuildTime = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    Configuration = $env:MBLD_CONFIGURATION
    Framework = $env:MBLD_TARGET_FRAMEWORK
    Version = $env:MBLD_VERSION
    Machine = $env:COMPUTERNAME
    User = $env:USERNAME
}
$buildInfo | ConvertTo-Json | Set-Content "$env:MBLD_PROJECT_DIR\BuildInfo.json"

Run only in Release mode (postbuild.ps1)

if ($env:MBLD_CONFIGURATION -ne 'Release') {
    Write-Host "Skipping - Release build only"
    exit 0
}

# Your release-only logic here
Write-Host "Running release post-build tasks..."

Copy additional files to output (postbuild.ps1)

# Copy config files
Copy-Item "$env:MBLD_PROJECT_DIR\config\*.json" -Destination $env:MBLD_TARGET_DIR -Force

# Copy native DLLs
$nativeDir = "$env:MBLD_PROJECT_DIR\native\$env:MBLD_PLATFORM"
if (Test-Path $nativeDir) {
    Copy-Item "$nativeDir\*.dll" -Destination $env:MBLD_TARGET_DIR -Force
}

Validate prerequisites (prebuild.ps1)

$ErrorActionPreference = 'Stop'

# Check required tools
if (-not (Get-Command 'node' -ErrorAction SilentlyContinue)) {
    throw "Node.js is required but not found in PATH"
}

# Check required environment variables
@('API_KEY', 'DATABASE_URL') | ForEach-Object {
    if (-not (Get-Item "env:$_" -ErrorAction SilentlyContinue)) {
        Write-Warning "$_ environment variable is not set"
    }
}

How It Works

This package uses MSBuild's native extensibility model:

1. NuGet Auto-Import: The package includes a .targets file in the build/ folder that NuGet automatically imports into consuming projects
2. Conditional Execution: Targets only execute when the corresponding script file exists
3. Build Hooks: Uses BeforeTargets="BeforeBuild" and AfterTargets="Build" to inject into the build pipeline

Why This Approach?

Configuration Options

You can customize behavior by setting MSBuild properties in your project file:

<PropertyGroup>
  
  <PwshBuildEventsEnabled>false</PwshBuildEventsEnabled>

  
  <PwshBuildEventsFolder>BuildScripts</PwshBuildEventsFolder>

  
  <PwshExecutable>pwsh.exe</PwshExecutable>

  
  <PwshBuildEventsCopySamples>false</PwshBuildEventsCopySamples>
</PropertyGroup>

Configuration Summary

Requirements

• .NET SDK 6.0 or later
• PowerShell Core 7.0+ (pwsh.exe) installed and available in PATH

Troubleshooting

Scripts not running?

1. Verify pwsh.exe is in your PATH: pwsh --version
2. Ensure scripts are in the correct location: Properties/prebuild.ps1 or Properties/postbuild.ps1
3. Check the script filename is exactly prebuild.ps1 or postbuild.ps1 (case-insensitive on Windows)
4. If you manually created the scripts (didn't use the auto-generated samples), ensure they are not blocked - see below

Execution Policy or Blocked Scripts?

This package runs scripts with -ExecutionPolicy Bypass, which handles most execution policy restrictions. However, if you're experiencing issues:

Check if your scripts are blocked:

Get-Item Properties\*.ps1 | Get-Item -Stream Zone.Identifier -ErrorAction SilentlyContinue

If you see output mentioning ZoneId=3 (Internet Zone), unblock the scripts:

Unblock-File -Path Properties\prebuild.ps1
Unblock-File -Path Properties\postbuild.ps1

Group Policy restrictions: If your organization enforces a strict execution policy via Group Policy, the -ExecutionPolicy Bypass flag used by this package should still work. However, if scripts still don't run, contact your IT administrator.

Note: Scripts auto-generated from the NuGet package sample files are never blocked because they are extracted locally, not downloaded from the internet.

Build fails with script error?

The build will fail if your script exits with a non-zero exit code. To allow the build to continue despite script errors:

# At the end of your script
exit 0

View detailed output

Run with increased verbosity:

dotnet build -v detailed

Uninstalling

Simply remove the package:

dotnet remove package DevPossible.PwshBuildEvents

The .targets file is automatically removed from the build process. Your scripts in Properties/ remain unchanged.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT License - see LICENSE file for details.

References

• MSBuild props and targets in a package
• Extending the Visual Studio build process
• MSBuild target build order