Skip to content

Add .NET file-based app sample and guide - #1066

Merged
Nikola Metulev (nmetulev) merged 6 commits into
mainfrom
zateutsch-dotnet-file-app-sample
Oct 14, 2026
Merged

Nikola Metulev (nmetulev) merged 6 commits into
mainfrom
zateutsch-dotnet-file-app-sample

Conversation

@zateutsch

@zateutsch Zach Teutsch (zateutsch) commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adds samples/dotnet-file-app and a step-by-step guide for .NET 10 file-based apps: a single .cs file with no project file, manifest, or assets. winapp run app.cs gives it package identity, generating the manifest and default assets in the build output. Because the sample references Microsoft.Windows.SDK.BuildTools.WinApp, plain dotnet run app.cs gives the same packaged launch.

The sample includes:

  • A README covering how to run, unregister, and customize the sample (#:property identity and capabilities, or an app.appxmanifest next to the file).
  • A Pester test, test.Tests.ps1. Phase 1 follows the guide from scratch: the new file prints Not packaged under dotnet run, then gets identity with winapp run. Phase 2 runs the sample with winapp run and then dotnet run. The test unregisters both apps afterwards. It only unregisters the sample if the test registered it, so a developer's own registration survives a skipped run.
  • CI wiring: the sample is added to the test-samples.yml matrix and gets the run's NuGet packages, so @*-* resolves to the branch build. The hard-coded expectations in artifact-workflow.Tests.ps1 are updated to match.

The new guide, docs/guides/dotnet-file-based.md, walks through:

  1. Creating a file-based app.
  2. Running it with identity.
  3. Naming the package.
  4. Running it with dotnet run.
  5. Cleaning up.

It also covers adding capabilities or a custom manifest, and links to docs/usage.md for the full reference. It's linked from the root README, docs/README.md, llms.txt, the .NET guide, the sample README, and the MS Learn TOC in port-mslearn-docs.ps1.

Usage Example

cd samples\dotnet-file-app
winapp run app.cs
# Package Family Name: winapp.samples.fileapp_<publisher-hash>
winapp unregister app.cs

Related Issue

Fixes #1064

Related to #1065. The test and guide use an explicit winapp unregister instead of --unregister-on-exit, which currently fails to clean up when not elevated.

Type of Change

  • ✨ New feature
  • 📝 Documentation
  • 🧪 Test update

Checklist

Screenshots / Demo

N/A. Console sample; see the usage example above.

Additional Notes

Local validation on Windows ARM64 with .NET SDK 10.0.401, using a Debug build of the CLI on PATH:

  • Every command in the guide, run in a temp folder: the output matched the guide, and no registrations were left behind.
  • samples\dotnet-file-app\test.Tests.ps1: 9/9 passed, and no registrations were left behind. The npm global install step was skipped locally; CI exercises it.
  • scripts\tests\artifact-workflow.Tests.ps1: 25/25 passed.
  • scripts\validate-mslearn-docs.ps1: passed. scripts\tests\validate-mslearn-docs.Tests.ps1: 37/37 passed.

Unlike the other .NET samples, there is no .gitignore: file-based builds go to %TEMP%\dotnet\runfile\, not the sample folder. There is also no MSIX packaging section; the guide points to the .NET guide for packaging.

Adds samples/dotnet-file-app: a single app.cs run with 'winapp run app.cs'
or 'dotnet run app.cs', with identity described by #:property directives
and no manifest or assets. Covered by a Pester sample test and the
test-samples CI matrix.

Fixes #1064

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 722ef99e-56b6-4428-976b-3761e371b3d4
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 722ef99e-56b6-4428-976b-3761e371b3d4
…un warning in README

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 722ef99e-56b6-4428-976b-3761e371b3d4
Copilot AI balanced review requested due to automatic review settings October 12, 2026 22:55
@zateutsch Zach Teutsch (zateutsch) added the agent-preparing Agent is addressing feedback or completing required validation and CI label Oct 12, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The manual workflow selector omits dotnet-file-app, preventing maintainers from running that sample alone.

1 open finding
What changed in this PR

Adds a minimal .NET 10 file-based app sample demonstrating packaged identity without a project file or authored manifest.

Changes:

  • Adds the sample, documentation, and two launch workflows.
  • Adds Pester coverage and CI matrix integration.
  • Updates sample listings and workflow assertions.
File Description
samples/​dotnet-file-app/​app.cs Implements the single-file sample.
samples/​dotnet-file-app/​README.md Documents usage and customization.
samples/​dotnet-file-app/​test.Tests.ps1 Tests creation, launch, and cleanup.
.github/​workflows/​test-samples.yml Adds the sample to CI.
scripts/​tests/​artifact-workflow.Tests.ps1 Updates workflow expectations.
README.md Lists the new sample.
docs/​usage.md Links to the complete example.

🧠 Review effort: Balanced


💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread .github/workflows/test-samples.yml Resolved
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact Baseline Current Delta
CLI (ARM64) 57.88 MB 57.88 MB ✅ 0.0 KB (0.00%)
CLI (x64) 57.90 MB 57.90 MB ✅ 0.0 KB (0.00%)
MSIX (ARM64) 24.05 MB 24.05 MB 📉 -0.2 KB (-0.00%)
MSIX (x64) 25.54 MB 25.54 MB 📈 +0.1 KB (+0.00%)
NPM Package 50.18 MB 50.18 MB 📈 +0.4 KB (+0.00%)
NuGet Package 50.29 MB 50.29 MB 📈 +0.3 KB (+0.00%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 8376 passed, 37 skipped out of 8413 tests in 1693.5s (+633.6s vs. baseline)

Test Coverage

✅ 87.6% line coverage, 82.3% branch coverage · ✅ no change vs. baseline

CLI Startup Time

53ms median (x64, winapp --version) · ✅ -10ms vs. baseline

Try This Build

Installs the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 1066
Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 1066

Run winapp-pr with no arguments to pick from a list of open PRs.


Updated 2026-10-13 00:08:22 UTC · commit 7299071 · workflow run

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 722ef99e-56b6-4428-976b-3761e371b3d4
@zateutsch Zach Teutsch (zateutsch) changed the title Add .NET file-based app sample Add .NET file-based app sample and guide Oct 12, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 722ef99e-56b6-4428-976b-3761e371b3d4
@zateutsch Zach Teutsch (zateutsch) added ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Oct 13, 2026
@nmetulev
Nikola Metulev (nmetulev) merged commit d399e31 into main Oct 14, 2026
45 checks passed
@nmetulev
Nikola Metulev (nmetulev) deleted the zateutsch-dotnet-file-app-sample branch October 14, 2026 05:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a .NET file-based app (single-file .cs) sample

3 participants