MSBuild Project Files

Overview

The Krypton Toolkit build system uses MSBuild project files (.proj) to orchestrate multi-project builds, NuGet package creation, and distribution archive generation. Project files are located under Scripts/Build/, Scripts/VS2022/, and Scripts/Current/; GitHub Actions use Scripts/Build/.

Each script .proj imports the repo root Directory.Build.props, which defines KryptonBuildOutputRoot and KryptonPackageOutputRoot. Those resolve to legacy Bin\ and Bin\Packages\ by default, or to artifacts\bin\ and artifacts\packages\ when MSBuild is invoked with /p:UseArtifactsOutput=true (as in CI). Clean, Push, and archive targets use $(ReleaseSourcePath), $(ReleasePackagesPath), and equivalent Canary/Nightly properties so they stay aligned with component OutputPath and PackageOutputPath.

Parallel builds

Command line: Local .cmd scripts, GitHub Actions, and ModernBuild pass /m (all logical CPUs) when invoking MSBuild.
Orchestration: nightly.proj sets BuildInParallel="true" on its Build <MSBuild> task. Other orchestration .proj files use the task default (true).
Ordering: Project references between Krypton.* libraries still apply; only independent work runs in parallel.

See Build System Overview and Build Scripts.

Project File Structure

All .proj files follow a similar structure:

Import global properties
Define configuration-specific properties
Define targets for Clean, Restore, Build
Define targets for package creation
Define targets for archive creation

Core Project Files

build.proj - Stable/Release Builds

Purpose: Builds stable production releases

Key properties (from Scripts/Build/build.proj):

<Import Project="..\..\Directory.Build.props" />
<Configuration>Release</Configuration>
<ReleaseSourcePath>$(KryptonBuildOutputRoot)Release\</ReleaseSourcePath>
<ReleasePackagesPath>$(KryptonPackageOutputRoot)Release\</ReleasePackagesPath>
<ReleaseBuildPath>$(ReleaseSourcePath)Zips\</ReleaseBuildPath>
<ReleaseZipName>Krypton-Release</ReleaseZipName>

Available Targets:

Clean

Cleans all Krypton component projects for the Release configuration.

msbuild /m build.proj /t:Clean

Restore

Restores NuGet packages for all Krypton components.

msbuild /m build.proj /t:Restore

Build (Default)

Builds all Krypton components. Depends on Restore.

msbuild /m build.proj /t:Build

CleanPackages

Deletes existing NuGet packages from $(ReleasePackagesPath) (legacy: Bin/Packages/Release/; artifacts: artifacts/packages/Release/).

msbuild /m build.proj /t:CleanPackages

PackLite

Creates NuGet packages for "lite" target frameworks (net48, net481, net8.0+).

Cleans projects and NuGet assets
Restores with TFMs=lite
Packs with TFMs=lite

msbuild /m build.proj /t:PackLite

PackAll

Creates NuGet packages for all target frameworks (net472-net10.0-windows).

Cleans projects and NuGet assets
Restores with TFMs=all
Packs with TFMs=all

msbuild /m build.proj /t:PackAll

Pack

Master packaging target. Depends on CleanPackages, PackLite, and PackAll. Generates both Lite and full packages.

msbuild /m build.proj /t:Pack

Push

Publishes NuGet packages to NuGet.org using nuget.exe.

msbuild /m build.proj /t:Push

Note: Requires NUGET_API_KEY environment variable or configured API key.

CreateReleaseZip

Creates ZIP archive of Release binaries.

Uses 7-Zip if available
Falls back to PowerShell Compress-Archive
Output: $(ReleaseBuildPath)Krypton-Release_<yyyyMMdd>.zip (under Bin/Release/Zips/ or artifacts/bin/Release/Zips/)

msbuild /m build.proj /t:CreateReleaseZip

CreateReleaseTar

Creates TAR.GZ archive of Release binaries.

Tries 7-Zip (recommended)
Falls back to Windows 10/11 tar command
Falls back to Git Bash tar
Output: same Zips folder as ZIP, e.g. .../Release/Zips/Krypton-Release_<yyyyMMdd>.tar.gz

msbuild /m build.proj /t:CreateReleaseTar

CreateAllReleaseArchives

Creates both ZIP and TAR.GZ archives.

msbuild /m build.proj /t:CreateAllReleaseArchives

canary.proj - Beta Pre-Release Builds

Purpose: Builds beta pre-release packages for early adopters

Key properties:

<Configuration>Canary</Configuration>
<CanarySourcePath>$(KryptonBuildOutputRoot)Canary\</CanarySourcePath>
<CanaryPackagesPath>$(KryptonPackageOutputRoot)Canary\</CanaryPackagesPath>
<CanaryBuildPath>$(CanarySourcePath)Zips\</CanaryBuildPath>
<CanaryZipName>Krypton-Canary</CanaryZipName>

Available Targets:

Clean - Clean Canary configuration
Restore - Restore packages
Build - Build Canary configuration
CleanPackages - Delete packages from $(CanaryPackagesPath)
PackAll - Create Canary packages (all TFMs, no Lite variant)
Pack - Master packaging target (CleanPackages + PackAll)
Push - Publish Canary packages
CreateCanaryZip - Create Canary ZIP archive
CreateCanaryTar - Create Canary TAR.GZ archive
CreateAllCanaryArchives - Create both archives

Key Differences from Stable:

No PackLite target (Canary always packs all TFMs)
Packages get -beta suffix in NuGet
Outputs under $(KryptonBuildOutputRoot)Canary\ and $(KryptonPackageOutputRoot)Canary\ (legacy Bin/... or artifacts/...)

nightly.proj - Alpha Nightly Builds

Purpose: Builds bleeding-edge alpha releases for developers and testers

Key properties:

<Configuration>Nightly</Configuration>
<NightlySourcePath>$(KryptonBuildOutputRoot)Nightly\</NightlySourcePath>
<NightlyPackagesPath>$(KryptonPackageOutputRoot)Nightly\</NightlyPackagesPath>
<NightlyBuildPath>$(NightlySourcePath)Zips\</NightlyBuildPath>
<NightlyZipName>Krypton-Nightly</NightlyZipName>

Available Targets:

Clean - Clean Nightly configuration
Restore - Restore packages
Build - Build Nightly configuration
Rebuild - Clean + Build
CleanPackages - Delete packages from $(NightlyPackagesPath)
PackAll - Create Nightly packages (all TFMs)
Pack - Master packaging target
Push - Publish Nightly packages
CreateNightlyZip - Create Nightly ZIP archive
CreateNightlyTar - Create Nightly TAR.GZ archive
CreateAllArchives - Create both archives

Key Differences:

Includes Rebuild target
Packages get -alpha suffix in NuGet
Outputs under $(KryptonBuildOutputRoot)Nightly\ and $(KryptonPackageOutputRoot)Nightly\

Build target (explicit cross-project parallelism):

<MSBuild Projects="@(Projects)"
         Properties="Configuration=$(Configuration);TFMs=all"
         BuildInParallel="true" />

canarylongtermstable.proj - Canary LTS (V105-LTS)

Purpose: Orchestrates Canary-configuration builds for the Canary LTS GitHub Actions workflow (.github/workflows/canary-lts-release.yml) on branch V105-LTS.

Usage: Same targets as canary.proj (Build, Pack, archives, and so on). CI invokes:

msbuild /m "Scripts/Build/canarylongtermstable.proj" /t:Build /p:Configuration=Canary /p:Platform="Any CPU" /p:UseArtifactsOutput=true

Note: The main canary branch release job in release.yml uses canary.proj; scheduled/manual Canary LTS publishing uses this file.

debug.proj - Debug Builds

Purpose: Local development debug builds

Key Properties:

<Configuration>Debug</Configuration>

Available Targets:

Clean - Clean Debug configuration
Restore - Restore packages
Build - Build Debug configuration

Key Differences:

No packaging or archive targets
Simplified for local development

installer.proj - Installer Builds

Purpose: Builds packages for demo installers

Key Properties:

<Configuration>Installer</Configuration>

Available Targets:

Clean - Clean Installer configuration
Restore - Restore packages
Build - Build Installer configuration
CleanPackages - Delete packages from the Installer folder under $(KryptonPackageOutputRoot)
PackAll - Create Installer packages
Pack - Master packaging target
Push - Publish Installer packages
CreateNightlyZip - Create Installer ZIP (reuses Nightly zip logic)

Special Notes:

WiX installers require build numbers ≤ 256
Version uses month number for Build component

Project File Patterns

Project Selection Pattern

All .proj files under Scripts/Build/ use this pattern to select Krypton projects (two levels up to the repo root):

<ItemGroup>
    <Projects Include="..\..\Source\Krypton Components\Krypton.*\*.csproj" />
</ItemGroup>

This selects:

Krypton.Toolkit\Krypton.Toolkit 2022.csproj
Krypton.Ribbon\Krypton.Ribbon 2022.csproj
Krypton.Navigator\Krypton.Navigator 2022.csproj
Krypton.Workspace\Krypton.Workspace 2022.csproj
Krypton.Docking\Krypton.Docking 2022.csproj

NuGet Asset Cleanup Pattern

Before packing, intermediate NuGet files are deleted:

<ItemGroup>
    <NugetAssets Include="..\..\Source\Krypton Components\Krypton.*\obj\*.json" />
    <NugetAssets Include="..\..\Source\Krypton Components\Krypton.*\obj\*.cache" />
    <NugetAssets Include="..\..\Source\Krypton Components\Krypton.*\obj\*.g.targets" />
    <NugetAssets Include="..\..\Source\Krypton Components\Krypton.*\obj\*.g.props" />
</ItemGroup>
<Delete Files="@(NugetAssets)" />

This ensures clean package generation.

MSBuild Invocation Pattern

Projects are built with configuration and TFM control. The nightly Build target enables cross-project parallelism explicitly:

<MSBuild Projects="@(Projects)"
         Properties="Configuration=$(Configuration);TFMs=all"
         BuildInParallel="true" />

Other orchestration .proj files omit BuildInParallel and use the MSBuild task default (true). Combine with /m on the msbuild.exe command line for multi-CPU compilation within the graph.

Key properties passed:

Configuration - Debug, Release, Canary, Nightly, Installer
TFMs - lite, all, or empty

Archive Generation

ZIP Archives

Uses multiple fallback methods:

7-Zip (preferred): Fast, best compression
PowerShell Compress-Archive: Built-in Windows

Example (stable release; sources use $(ReleaseSourcePath) so archives follow the same root as binaries):

<!-- 7-Zip method -->
<Exec Command="7z.exe a -tzip &quot;$(ReleaseBuildPath)\$(ReleaseZipName)_$(StringDate).zip&quot; &quot;$(ReleaseSourcePath)*&quot; -x!*.json -x!*.pdb"
      Condition="Exists('C:\Program Files\7-Zip\7z.exe')" />

<!-- PowerShell fallback -->
<Exec Command="powershell.exe -Command &quot;Get-ChildItem '$(ReleaseSourcePath)*' -Recurse | Where-Object {$_.Extension -notin '.json','.pdb'} | Compress-Archive -DestinationPath '$(ReleaseBuildPath)\$(ReleaseZipName)_$(StringDate).zip' -Force&quot;"
      Condition="!Exists('C:\Program Files\7-Zip\7z.exe')" />

TAR.GZ Archives

Uses multiple fallback methods:

7-Zip: Creates tar then compresses to tar.gz
Windows tar: Native tar in Windows 10/11
Git Bash tar: Uses Git's bundled tar

Custom Target Execution

Execute Specific Target

msbuild /m build.proj /t:TargetName

Execute Multiple Targets

msbuild /m build.proj /t:Clean;Build

Override Configuration

msbuild /m build.proj /t:Build /p:Configuration=Debug

Override TFMs

msbuild /m build.proj /t:Build /p:TFMs=lite

Artifacts output layout (CI / optional local)

msbuild /m Scripts\Build\build.proj /t:Build /p:UseArtifactsOutput=true

Verbose Output

msbuild /m build.proj /t:Build /v:detailed

Save to Log File

msbuild /m build.proj /t:Build /fl /flp:logfile=build.log

Binary Log

msbuild /m build.proj /t:Build /bl:build.binlog

Best Practices

1. Clean Before Major Builds

msbuild /m build.proj /t:Clean;Build

2. Use Rebuild for Complete Rebuild

msbuild /m nightly.proj /t:Rebuild

3. Test Packaging Locally Before Push

msbuild /m build.proj /t:Pack
REM Verify packages under artifacts/packages/Release/ or Bin/Packages/Release/ (depends on UseArtifactsOutput)
msbuild /m build.proj /t:Push

4. Use Binary Logs for Troubleshooting

msbuild /m build.proj /t:Build /bl:build.binlog
# View with MSBuild Structured Log Viewer

5. Parallel builds

Scripts and CI already pass /m. To cap CPU use:

msbuild /m:4 build.proj /t:Build
msbuild /m:1 build.proj /t:Build

Build Scripts - Command-line build scripts
Directory.Build Configuration - Property inheritance
NuGet Packaging - Package configuration
Version Management - Versioning details

MSBuild Project Files

Overview

Parallel builds

Project File Structure

Core Project Files

build.proj - Stable/Release Builds

Clean

Restore

Build (Default)

CleanPackages

PackLite

PackAll

Pack

Push

CreateReleaseZip

CreateReleaseTar

CreateAllReleaseArchives

canary.proj - Beta Pre-Release Builds

nightly.proj - Alpha Nightly Builds

canarylongtermstable.proj - Canary LTS (V105-LTS)

debug.proj - Debug Builds

installer.proj - Installer Builds

Project File Patterns

Project Selection Pattern

NuGet Asset Cleanup Pattern

MSBuild Invocation Pattern

Archive Generation

ZIP Archives

TAR.GZ Archives

Custom Target Execution

Execute Specific Target

Execute Multiple Targets

Override Configuration

Override TFMs

Artifacts output layout (CI / optional local)

Verbose Output

Save to Log File

Binary Log

Best Practices

1. Clean Before Major Builds

2. Use Rebuild for Complete Rebuild

3. Test Packaging Locally Before Push

4. Use Binary Logs for Troubleshooting

5. Parallel builds

Related Documentation