Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 46 additions & 2 deletions docs/dotnet-run-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,9 +165,53 @@ The package only activates when **all** of the following are true (gated by the
2. `WindowsPackageType` is not set to `None` (absence of the property means packaged).
3. `OutputType` is not `Library` — both `Exe` (packaged console apps via execution alias) and `WinExe` (WinUI apps) are supported.
4. The target platform identifier is `windows` (derived from `$(TargetPlatformIdentifier)` if set, else from `$(TargetFramework)`). In multi-targeted projects (e.g. MAUI `net*-android;net*-ios;net*-windows10.0.19041.0`), the targets are inert for non-Windows TFMs.
5. `WinAppManifestPath` resolves to an existing file. The targets auto-detect the manifest by checking the output directory first (`$(OutputPath)AppxManifest.xml`, `$(OutputPath)Package.appxmanifest`, `$(OutputPath)appxmanifest.xml`) and then the project directory (`AppxManifest.xml`, `Package.appxmanifest`, `appxmanifest.xml`); a consumer-supplied `WinAppManifestPath` is honored as-is. Output-directory paths are accepted because frameworks like MAUI generate the manifest at build time into `$(OutputPath)` from platform / msbuild props; without that the gate could never activate for transitive MAUI head apps.
5. `WinAppManifestPath` resolves to an existing file, **or** the project is a .NET file-based app. The targets auto-detect the manifest by checking the output directory first (`$(OutputPath)AppxManifest.xml`, `$(OutputPath)Package.appxmanifest`, `$(OutputPath)appxmanifest.xml`) and then the project directory (`AppxManifest.xml`, `Package.appxmanifest`, `appxmanifest.xml`); a consumer-supplied `WinAppManifestPath` is honored as-is. Output-directory paths are accepted because frameworks like MAUI generate the manifest at build time into `$(OutputPath)` from platform / msbuild props; without that the gate could never activate for transitive MAUI head apps.

This gating ensures the package is safe to consume transitively (e.g. when re-exported by a library): unrelated projects (libraries, test projects, console apps without manifests, non-Windows TFMs) see no winapp activity and no impact on `dotnet run`.
This gating ensures the package is safe to consume transitively (e.g. when re-exported by a library): unrelated projects (libraries, test projects, project-based console apps without manifests, non-Windows TFMs) see no winapp activity and no impact on `dotnet run`. The manifest requirement is a project-based one; a file-based app activates without an authored manifest, as described next.

### File-based apps

A [file-based app](https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/sdk#file-based-apps) — a single `.cs` run with `dotnet run app.cs` — has no authored manifest by design; its identity comes from the `#:property` directives in the file. Condition 5 therefore accepts the file-based case instead of a manifest, detected through the `FileBasedProgram` and `EntryPointFilePath` properties that the SDK writes into the generated virtual project. Conditions 1-4 still apply, so the `.cs` must declare a Windows target framework:

```csharp
#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property TargetFramework=net10.0-windows10.0.19041.0
#:property OutputType=Exe
```

Manifest auto-detection is skipped entirely for a file-based app and resolution is left to the CLI, for two reasons: several `.cs` files can share one directory, so a directory-scoped `Package.appxmanifest` cannot be assumed to belong to this app; and the CLI generates its own manifest into the build output, which auto-detection would otherwise pick up on the second run and pin as a stale identity.

The hand-off also differs. A `.csproj` passes its output folder, which the CLI treats as a pre-built layout. A `.cs` has to be passed as the input, because manifest inference is only reachable from the CLI's single-file mode — so `no-build` is added to keep `dotnet run`'s build the only one, and `RuntimeIdentifier` is forwarded so the CLI reads the same output folder `dotnet run` wrote to rather than injecting a host RID of its own:

```
winapp run <app.cs> --no-build --configuration "Debug" -p "RuntimeIdentifier=<rid>" ...
```

Because the CLI evaluates the `.cs` again to plan the manifest, and that evaluation cannot see the properties the outer build was invoked with, every property the CLI reads is carried across explicitly. That covers the identity-shaping ones (`WinAppPackageName`, `WinAppDisplayName`, `WinAppPublisher`, `WinAppVersion`, `WinAppDescription`, `WinAppCapabilities`, `WinAppManifestPath`), the packaging mode (`WindowsPackageType`), whether the app bundles the Windows App Runtime (`WindowsAppSDKSelfContained`), and the build inputs that decide which file is packaged (`AssemblyName`, `OutputPath`, `OutDir`, `MSBuildProjectExtensionsPath`, `OutputType`, `TargetFramework`, `Version`). This is what makes a command-line override take effect:

```bash
dotnet run app.cs -p:WinAppPackageName=Contoso # registers as Contoso
dotnet run app.cs -p:AssemblyName=Contoso # packages Contoso.exe
dotnet run app.cs -p:OutDir=.\out\ # launches what was built in .\out\
```

`OutDir` is carried alongside `OutputPath` because it is the property MSBuild actually writes the executable to. Setting it moves the output while leaving `OutputPath` at its default, so forwarding `OutputPath` alone would point the CLI at a directory the build never wrote to. `MSBuildProjectExtensionsPath` is carried for the same reason on the input side: it is the folder `project.assets.json` is written into, so relocating the intermediate directory with `-p:BaseIntermediateOutputPath=custom_obj\` would otherwise leave the CLI reading a default path that holds a stale package graph or none at all.

Values are percent-escaped on the way across (`%`, `;`, `,`, `"` and `\`), so a capability list such as `internetClient;privateNetworkClientServer` or a publisher containing a comma survives intact; MSBuild decodes them again on the other side. The configuration and runtime identifier in the leading tokens are escaped the same way, so a value ending in a backslash cannot escape its closing quote and swallow the rest of the command line.

A line break is refused rather than escaped. `winapp run` from the `RunPackagedApp` target goes through a generated command script, where a newline inside a value ends the line and turns whatever follows into a separate command. No manifest metadata is legitimately multi-line, so a value containing one fails the build with a message naming the properties to check, instead of being silently stripped and registering an identity you did not ask for.

Forwarding a value that came from a `#:property` directive is a no-op, since the CLI reads the directive itself. An empty value is forwarded rather than skipped for the identity properties, for `WindowsPackageType`, and for `WindowsAppSDKSelfContained`, because the CLI treats an empty property exactly as it treats an absent one: that is what makes `dotnet run app.cs -p:WinAppPackageName=` clear a directive instead of leaving the CLI to re-read it. The same applies to `dotnet run app.cs -p:WindowsAppSDKSelfContained=`, which drops back to a framework-dependent launch; without the empty value the CLI would keep generating a manifest that requires the Windows App Runtime for a build that no longer bundles it. `WinAppRunUseExecutionAlias` is forwarded only when it is empty, because a `true` or `false` already rides on the `--with-alias` / `--without-alias` switch. The build inputs are the exception in the other direction and are forwarded only when set, since the SDK always gives them a value. The SDK's derived outputs (`TargetDir`, `RunCommand`, `RunArguments`, `ProjectAssetsFile`) are left alone so the CLI still derives them itself, from the inputs above.

#### Declaring an architecture

A file-based app that does not name an architecture builds `AnyCPU`, which a self-contained Windows App SDK app cannot use. Declare one in the file:

```csharp
#:property RuntimeIdentifier=win-x64
```

`winapp run app.cs` injects a `win-<host>` runtime identifier when the file declares none, but `dotnet run app.cs` does not: the SDK owns that build, and silently changing its architecture because a package happens to be referenced would move the output from under a build the user invoked directly. Declaring the property makes both entry points build and launch the same thing.

## Build Scripts

Expand Down
54 changes: 54 additions & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -870,6 +870,8 @@ own manifest — see [Bring your own manifest](#bring-your-own-manifest) below.
winapp run counter.cs
```

Or run it with plain `dotnet run` — see [Running with `dotnet run`](#running-with-dotnet-run) below.

You do not author a manifest. Describe the package with `#:property` directives instead:

```csharp
Expand Down Expand Up @@ -1038,6 +1040,58 @@ activation — see the console note above; that choice is separate from whether
identity options (`--no-launch`, `--with-alias`, `--without-alias`, `--clean`, `--unregister-on-exit`,
`--manifest`, `--output-appx-directory`) apply to packaged apps only.

##### Running with `dotnet run`

You don't have to type `winapp` at all. Reference the
[`Microsoft.Windows.SDK.BuildTools.WinApp`](../src/winapp-NuGet/README.md) package from the file and
plain `dotnet run` gives you the same packaged launch:

```csharp
#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);
```

```bash
dotnet run counter.cs
```

The package's MSBuild targets redirect the run to winapp, which packages, registers, and launches the
app that `dotnet run` just built — it is not rebuilt. Manifest handling is unchanged: winapp resolves
it exactly as it does for `winapp run`, so `#:property WinAppManifestPath=…` and a
`<filename>.appxmanifest` beside the `.cs` are both honoured (see
[Bring your own manifest](#bring-your-own-manifest)), a directory-wide `Package.appxmanifest` is still
ignored, and otherwise one is generated from your `#:property` directives and refreshed every run.

Two conditions have to hold for the redirect to happen:

| Directive | Why |
|-----------|-----|
| `#:package Microsoft.Windows.SDK.BuildTools.WinApp@*` | the targets doing the redirect ship in this package |
| `#:property TargetFramework=net10.0-windows…` | a plain `net10.0` file is left alone, so it runs unpackaged |

Adding `#:property WindowsPackageType=None` also leaves the file alone: `dotnet run` then runs the
`.exe` directly, without identity. Use `winapp run` for the unpackaged path if you want the matching
Windows App Runtime installed first.

Set `#:property EnableWinAppRunSupport=false` to opt out of the redirect entirely, and the
`WinAppRun*` properties described under
[Configuration](../src/winapp-NuGet/README.md#configuration) to shape the launch — for example:

```csharp
#:property WinAppRunUnregisterOnExit=true
```

If `dotnet run` runs the app unpackaged when you expected identity, ask MSBuild why. Use
`dotnet build`, not `dotnet msbuild` — only `dotnet build` synthesizes the virtual project that a
file-based app is compiled through:

```bash
dotnet build counter.cs -t:WinAppRunSupportInfo
```

Single-file mode requires the **.NET SDK 10.0.300 or newer**.

**The registration outlives the run.** `winapp run counter.cs` leaves the package registered after the
Expand Down
1 change: 1 addition & 0 deletions plugins/winapp/skills/winapp-setup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,7 @@ Describe the package with `#:property` directives in the file. All are optional:
- **Console apps print to the terminal by default.** An app with `OutputType=Exe` is launched through an execution alias rather than AUMID activation, because an AUMID-launched packaged app has no console and would print nothing. Pass `--without-alias` (or set `#:property WinAppRunUseExecutionAlias=false`) to force AUMID; pass `--with-alias` to get one for a windowed app. The alias is named from the package *family* name with a `winapp-` prefix (`com.contoso.counter` → `winapp-com.contoso.counter_<publisherhash>.exe`), so it can never contend with a real command on PATH or with another publisher's same-named app; `winapp run` prints the name it registered. An authored manifest's own alias is used as-is. If another package already owns the name, winapp reports it — falling back to AUMID when it inferred the alias for you, and failing the run when you asked for one explicitly with `--with-alias` or `WinAppRunUseExecutionAlias=true`, rather than launching the wrong app.
- **Rejected options** (the file configures itself): `-f` ⇒ `#:property TargetFramework=…`; `--project` ⇒ not applicable. `--arch`/`-r` work as in project mode and default to the **current winapp process architecture** — required for self-contained WinAppSDK apps, which fail as `AnyCPU`. Everything else works as usual.
- **The package outlives the run.** winapp says so the first time it registers an app. Remove it with `winapp unregister counter.cs` (no manifest path needed — it resolves the same identity), or run with `--unregister-on-exit`.
- **`dotnet run counter.cs` works too.** Add `#:package Microsoft.Windows.SDK.BuildTools.WinApp@*` and a Windows TFM (`#:property TargetFramework=net10.0-windows10.0.19041.0`) and the package's targets redirect the run to winapp — same packaged launch, no rebuild, no `winapp` command. A plain `net10.0` file or `#:property WindowsPackageType=None` is left alone and runs unpackaged; `#:property EnableWinAppRunSupport=false` opts out. Diagnose with `dotnet build counter.cs -t:WinAppRunSupportInfo` (`dotnet msbuild` cannot load a `.cs`).
- Requires **.NET SDK 10.0.300+**.

> The default identity includes a short hash of the file's path (`counter.cs` → `counter-a1b2c3d4`), so two `counter.cs` files in different folders are separate apps with separate `LocalState`. It is stable across edits and re-runs, and changes only if the file moves. Set `WinAppPackageName` to pick a stable identity yourself. The Start menu shows `WinAppDisplayName`, not the identity.
Expand Down
21 changes: 18 additions & 3 deletions src/winapp-NuGet/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,6 @@ dotnet run
```

### Transitive consumption (library author)

If you ship a library that you want to expose this package's behavior to its consumers (e.g. a MAUI library wrapper), reference the package with `PrivateAssets="none"` and `IncludeAssets="build;buildTransitive"`:

```xml
Expand All @@ -42,7 +41,7 @@ If you ship a library that you want to expose this package's behavior to its con
IncludeAssets="build;buildTransitive" />
```

The package ships its props and targets in both `build/` and `buildTransitive/`, so consumers of your library will pick them up automatically. The targets only activate when the consuming project is a packaged Windows app (has an appxmanifest, OutputType is not `Library`, target platform is `windows`); they are no-ops in unrelated TFMs (e.g. the `net*-android` / `net*-ios` TFMs of a multi-targeted MAUI app), libraries, and test projects.
The package ships its props and targets in both `build/` and `buildTransitive/`, so consumers of your library will pick them up automatically. The targets only activate when the consuming project is a packaged Windows app (has an appxmanifest, OutputType is not `Library`, target platform is `windows`); they are no-ops in unrelated TFMs (e.g. the `net*-android` / `net*-ios` TFMs of a multi-targeted MAUI app), libraries, and test projects. The appxmanifest requirement applies to project-based consumers; a [.NET file-based app](https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/sdk#file-based-apps) has no authored manifest by design and activates without one, as described under [Troubleshooting](#dotnet-run-appcs-is-not-intercepted-file-based-app-runs-unpackaged).

## How It Works

Expand Down Expand Up @@ -141,10 +140,26 @@ The gate (`_WinAppRunSupportActive`) requires **all five** of these to be true:
2. `WindowsPackageType` is not `None`.
3. `OutputType` is not `Library` (must be `Exe`, `WinExe`, etc.).
4. `_WinAppEffectiveTargetPlatformIdentifier` is `windows` (derived from `$(TargetPlatformIdentifier)` if set, else from `$(TargetFramework)`).
5. A manifest exists in the project directory (`Package.appxmanifest`, `AppxManifest.xml`, or `appxmanifest.xml`) **or** you explicitly set `WinAppManifestPath` to a file that exists.
5. Either a manifest exists in the project directory (`Package.appxmanifest`, `AppxManifest.xml`, or `appxmanifest.xml`) or you explicitly set `WinAppManifestPath` to a file that exists — **or** the project is a .NET file-based app (a single `.cs` run with `dotnet run app.cs`), which has no authored manifest by design and gets its identity inferred instead.

Look at the `WinAppRunSupportInfo` output — the property whose value disagrees with the list above is the one that's keeping the gate inactive.

### `dotnet run app.cs` is not intercepted (file-based app runs unpackaged)

A [file-based app](https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10/sdk#file-based-apps) has to declare a Windows target framework for condition 4 above to hold. Without one, the gate stays inactive and the app runs unpackaged:

```csharp
#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property TargetFramework=net10.0-windows10.0.19041.0
#:property OutputType=Exe
```

To see the gate inputs for a `.cs`, pass the file to the diagnostic target. Use `dotnet build`, not `dotnet msbuild` — only `dotnet build` synthesizes the virtual project that a file-based app is compiled through:

```bash
dotnet build app.cs -t:WinAppRunSupportInfo
```

### Application fails to launch

Ensure your `appxmanifest.xml` is correctly configured with:
Expand Down
Loading
Loading