building-code

# Building the WinForms Repository > ## 🛑 TENET — Build the solution ONLY with `build.cmd` > > **Never** build, validate, or declare the WinForms solution "clean" with a plain > `dotnet build` / `dotnet msbuild` of `Winforms.sln`. Only **`build.cmd`** (Arcade) applies the > repository's CI configuration — the **PublicAPI analyzer (RS0016/RS0017)**, the code-style and > documentation analyzers, and **`-warnAsError`**. A plain `dotnet build` silently downgrades or > skips these, so **"0 warnings" there does NOT mean CI is green** — the very same change can fail > the official build with errors. > > * **Full / release / package / "is it clean?" verification → always `build.cmd`** (see §2). > * A single-project `dotnet build` (see §3) is an **inner-loop convenience only**. It is fine while > iterating, but you **must re-verify with `build.cmd` before claiming a change builds cleanly**. > * If `build.cmd` cannot run in your environment, the closest fallback is > `dotnet build <project> /p:ContinuousIntegrationBuild=true /p:TreatWarningsAsErrors=true` — and > you must say so explicitly rather than implying a `build.cmd` result. ## Prerequisites * Windows is required for WinForms runtime scenarios, test execution, and Visual Studio workflows. * Linux is supported for command-line restore/build only; use `build.sh` instead of `build.cmd` / `Restore.cmd`. * Visual Studio 2022 (for IDE builds) — see `WinForms.vsconfig` for required workloads. * The repo-local .NET SDK (specified in `global.json`) is used automatically by `build.cmd` and `Restore.cmd`. You do **not** need a machine-wide SDK install for command-line builds. --- ## 1 Restore Restoring downloads the repo-local SDK and all NuGet packages. ``` .\Restore.cmd ``` Under the hood this runs: ```powershell eng\common\Build.ps1 -NativeToolsOnMachine -restore ``` You can pass any extra `Build.ps1` flags after `Restore.cmd`, e.g. `.\Restore.cmd -configuration Release`. --- ## 2 Full Solution Build (preferred) > **Always use `build.cmd` (Arcade) for full, release, and package builds.** Do **not** use a plain > `dotnet build` of the solution for these — only `build.cmd` guarantees the Arcade-supported build > options and the download of the correct base SDK (`global.json`) needed to compile. Plain > `dotnet build` is reserved for the fast single-project inner loop (see Section 3), and even then > only after at least one successful `build.cmd` / `Restore.cmd`. ``` .\build.cmd ``` This restores **and** builds `Winforms.sln` in `Debug|Any CPU` by default. Under the hood this runs: ```powershell eng\common\Build.ps1 -NativeToolsOnMachine -restore -build -bl ``` ### 2.1 Full (clean) test build — required workflow For a full, clean build of the whole solution, **clean the artifacts first, then build**: ```powershell # 1. Clean the artifacts folder. .\build -clean # 2. Build the full solution. .\build ``` **Reporting requirement:** a full build is long-running, so while it runs **report progress back to the user in the console to bridge the wait and give early orientation.** As assemblies complete, report which assemblies have been **built successfully** and which **failed and with how many errors**. Prefer running the build with a binary log (the default `-bl`) and/or stream the console output so per-project results can be surfaced as they happen rather than only at the end. ### 2.2 Release build ```powershell .\build -configuration release ``` ### 2.3 Creating packages ```powershell # Debug packages .\build -pack # Release packages .\build -configuration release -pack ``` ### 2.4 Full `Build.ps1` parameter list `build.cmd` forwards every extra argument to `eng\common\Build.ps1`. The full surface is: ``` Build.ps1 [-configuration <string>] [-platform <string>] [-projects <string>] [-verbosity <string>] [-msbuildEngine <string>] [-warnAsError <bool>] [-warnNotAsError <string>] [-nodeReuse <bool>] [-buildCheck] [-restore] [-deployDeps] [-build] [-rebuild] [-deploy] [-test] [-integrationTest] [-performanceTest] [-sign] [-pack] [-publish] [-clean] [-productBuild] [-fromVMR] [-binaryLog] [-binaryLogName <string>] [-excludeCIBinarylog] [-ci] [-prepareMachine] [-runtimeSourceFeed <string>] [-runtimeSourceFeedKey <string>] [-excludePrereleaseVS] [-nativeToolsOnMachine] [-help] [-properties <string[]>] [<CommonParameters>] ``` ### Common flags | Flag | Short | Description | |------|-------|-------------| | `-configuration <Debug\|Release>` | `-c` | Build configuration (default: `Debug`) | | `-platform <x86\|x64\|Any CPU>` | | Platform (default: `Any CPU`) | | `-restore` | `-r` | Restore only | | `-build` | `-b` | Build only (skip restore if already done) | | `-rebuild` | | Clean + build | | `-clean` | | Delete build artifacts | | `-pack` | | Create NuGet packages (`Microsoft.Private.Winforms`) | | `-bl` / `-binaryLog` | | Emit `artifacts\log\Debug\Build.binlog` | | `-ci` | | CI mode (stricter warnings, signing, etc.) | | `-test` | `-t` | Build **and** run unit tests | | `-integrationTest` | | Build **and** run integration / functional tests | ### Examples ```bash # Release build .\build.cmd -configuration Release # Build and run unit tests .\build.cmd -test # Create NuGet package .\build.cmd -pack ``` --- ## 3 Optimized Building a Single Project (fast inner-loop) > **Inner-loop only.** Use plain `dotnet build` of a single project **only** for quick iteration on > one project, and **only after** at least one successful `.\build.cmd` / `.\Restore.cmd`. It does > **not** guarantee the Arcade-supported build options or the download of the correct base SDK, so it > must **never** be used for a full solution build, a release build, packaging, or any build whose > result you intend to report as authoritative. For those, always use `build.cmd` (Section 2). Prefer rebuilding just the project(s) with recent changes by using the standard `dotnet build` command, **after** at least one initial successful full restore (via `.\Restore.cmd` or `.\build.cmd`). This is **much** faster than building the whole solution. ```bash # Build a single src project dotnet build src\System.Windows.Forms\System.Windows.Forms.csproj # Build a single test project dotnet build src\test\unit\System.Windows.Forms\System.Windows.Forms.Tests.csproj # Release configuration dotnet build src\System.Windows.Forms\System.Windows.Forms.csproj -c Release ``` > **Tip:** The repo-local SDK must be on your `PATH`. Running `.\start-code.cmd` > or `.\start-vs.cmd` prepends it automatically. From a plain terminal you can > also run `.\Restore.cmd` first (it sets up the SDK). --- ## 4 Building from Visual Studio 1. Run `.\Restore.cmd` (one-time, or after SDK/package changes). 2. Run `.\start-vs.cmd` — opens `Winforms.sln` with the repo-local SDK on `PATH`. 3. Build normally (<kbd>Ctrl+Shift+B</kbd>). ## 5 Building from Visual Studio Code 1. (Optional) `.\Restore.cmd` 2. `.\start-code.cmd` — opens the workspace with the repo-local SDK on `PATH`. 3. Build from the integrated terminal: `.\build.cmd` or `dotnet build <project>`. --- ## Build Outputs | Artifact | Location | |----------|----------| | Binaries | `artifacts\bin\<Project>\Debug\<tfm>\` | | Logs | `artifacts\log\` | | Binary log | `artifacts\log\Debug\Build.binlog` | | Test results | `artifacts\TestResults\` | | NuGet packages | `artifacts\packages\` | Use the [MSBuild Structured Log Viewer](https://msbuildlog.com/) to inspect `.binlog` files when troubleshooting build errors. --- ## Troubleshooting * **Most errors are compile errors** — fix them as usual. * **MSBuild task errors** — inspect `artifacts\log\Debug\Build.binlog`. * **SDK version mismatch** — the repo pins its SDK in `global.json`; run `.\Restore.cmd` to ensure the correct SDK is available. * **VS preview features** — if using a non-Preview VS, enable *Tools → Options → Environment → Preview Features → Use previews of the .NET SDK*.