Maui Preview Helper

MAUI preview helper

Componentized helper for standing up and maintaining .NET MAUI preview / dogfood environments. Seven optional, composable capabilities — do only what the user asks; each maps to a reference doc with the depth.

Operating principles

• Agent-first / CLI-first. Reason and drive az / dotnet / code / darc / gh directly. The bundled pwsh scripts exist only for the fiddly deterministic bits (AzDO artifact resolution, rollback-file construction, release tracker). Don't wrap what a CLI already does.
• Pin exact versions. A wrong SDK band cascades into wrong workloads and broken restores. When the user is vague, look it up and offer a choice — don't guess.
• Match versions across layers: the staged local MAUI package version == <MauiVersion> in the project == the microsoft.net.sdk.maui entry in the rollback file. Keep them identical.
• Isolate the preview SDK in a dedicated install dir (workloads are scoped to DOTNET_ROOT), so it never collides with a global install.
• Cross-platform: detect OS/arch and pick the right installer/VSIX/paths. Confirm the target platform when it's ambiguous (e.g. building for iOS from Windows).
• Only install missing prereqs for the capabilities in play, and ask before installing system tooling. See references/prerequisites.md.
• Degrade gracefully for external users. Several sources are Microsoft-internal (Release Tracker, darc/Maestro, devdiv builds). Detect that before routing a user toward them, take the public path when one exists, and say plainly when one doesn't — never surface a raw 401/403 or tell someone to az login for something they can't be granted. See Access tiers.

Capabilities → route to the right reference

Load a reference before acting on its capability — each has the exact URL patterns, script invocations, gotchas, and stop signals. Don't rely on this router alone for the details.

Access tiers

Not everything here is reachable outside Microsoft. Establish the tier once, up front, then route accordingly — don't discover it via a 401 halfway through a setup.

Detect before routing:

az account show >/dev/null 2>&1 && echo "az: signed in" || echo "az: not signed in"
pwsh scripts/Get-DotNetReleaseStatus.ps1 | head -3   # leading lines name the source actually used

If the release output is headed "Public release data", treat the session as external: skip devdiv and darc entirely, and target only shipped/announced releases. Unshipped previews are internal-only — don't imply they're obtainable.

Typical end-to-end flow (full dogfood setup)

Most requests are a subset of this. Adapt to what the user asked for.

1. Prereqs — detect missing tools for the capabilities you'll use; install/authenticate.
2. Release lookup — resolve the exact SDK version + MAUI version + build id(s); if vague, run the tracker and let the user pick.
3. Download — install the preview SDK into a dedicated dir; stage the build's NuGet packages into a local source folder; note the exact MAUI package version.
4. NuGet.config — point the workspace at the local source + dotnet{N} / dotnet-public.
5. Workloads — install into the pinned SDK via workload set or a rollback file (New-WorkloadRollbackFile.ps1 from the maui branch, with -MauiVersion/overrides).
6. Project properties — set <MauiVersion> + the feature group the user is testing (Directory.Build.props or .csproj), plus VS Code / VS settings at the correct scope.
7. VS Code VSIX — install C# → C# Dev Kit → .NET MAUI Dev Kit for this OS/arch.
8. Verify — dotnet workload list, dotnet restore/build, code --list-extensions.

Bundled scripts (in scripts/)

• Get-AzdoArtifact.ps1 — resolve + download any AzDO artifact (whole zip / single file / list), public or devdiv-authenticated; -Extract, -FlattenNupkg. Powers capabilities 2 & 5.
• New-WorkloadRollbackFile.ps1 — build a rollback JSON from a dotnet/maui branch's Rollback.in.json + Versions.props, with -Band / -MauiVersion / -Override. Capability 3.
• Get-DotNetReleaseStatus.ps1 + ReleaseTrackerApi.ps1 — bundled .NET Release Tracker (capability 1). Needs az login. If the standalone dotnet-release-tracker plugin is installed, you may use it instead — same API.

Get-AzdoArtifact.ps1 and New-WorkloadRollbackFile.ps1 emit a one-line [SKILL_SUMMARY] {json} with structured results — reason over that, don't just echo it. (The bundled release-tracker script prints human-readable release blocks instead of a summary line; parse those directly.)

Key facts (details in references)

• AzDO orgs: dnceng-public (public — whole-artifact downloads are anonymous; file listing / single-file fetches may still mint an az token, done automatically when az is present) vs devdiv/DevDiv (private, always needs an az token; resource 499b84ac-1321-427f-aa17-267ca6975798).
• Preview package feeds are dotnet{N} (N = major, e.g. dotnet11) on dnceng/public.
• Rollback file = flat JSON { "manifest.id": "version/sdk-band" }; the microsoft.net.sdk.maui version is only knowable from the CI build (supply it explicitly).
• <MauiVersion> is the single source of truth — the SDK pins all MAUI package refs to it. Any explicit MAUI PackageReference must use Version="$(MauiVersion)", never a literal (project-properties.md).
• XAML SourceGen Hot Reload needs three props together: MauiXamlInflator=SourceGen, MauiXamlHotReload=SourceGen, EnableMauiIncrementalHotReload=true. Keep UseMonoRuntime=false everywhere — Mono on iOS is unsupported in .NET 11 (NETSDK1242), superseding the old P5 "iOS HR needs Mono" guidance (project-properties.md).
• Layering a branch/PR MAUI build onto a base release: stage its nupkgs into the same local source and bump only <MauiVersion> (download-builds.md).
• Authenticated feeds (401 on restore): mint an az token for the feed's org (resource 499b84ac-…) or a Packaging-read PAT; wire via packageSourceCredentials, never commit it (nuget-config.md).
• VS Code HR settings csharp.experimental.debug.hotReload / csharp.debug.hotReloadVerbosity are machine-scoped → User settings.json; verbosity value is singular "diagnostic".

Stop signals

• Do only the requested capabilities — don't run a full setup when asked for one piece.
• Once the target versions are pinned, stop looking them up; once dotnet restore/workload list shows the intended versions, stop reconfiguring.
• Download one installer/VSIX per OS/arch, not the whole matrix.
• Ask the user (don't guess) when a version, branch, build id, target platform, or the MAUI manifest version is unknown.

Improve This Skill

For the agent: If this skill was used during the session and you or the user encountered friction — unexpected failures, stale guidance, repeated workarounds, or unclear routing — you may offer a brief skill-quality review at a natural stopping point (on task completion, before /clear, or when the user asks what to do next):

"This session used maui-preview-helper. Want me to capture privacy-safe feedback for the skill author using skill-reflect?"

If the user says yes, invoke the skill-reflect skill. Pass this skill's identity so attribution is exact — the nudge carries context. Include the skill name (and optionally its source repo) when invoking:

Run skill-reflect. Skill used this session: maui-preview-helper (source repo: Redth/maui-skillz).

Rules — never deviate:

• Consent-first. Offer; never run automatically. skill-reflect runs only on the user's explicit yes.
• Only on friction. Routine, smooth sessions need no review.
• Nothing leaves the machine without a second consent step inside skill-reflect.