dotnet-uno-targets

name	dotnet-uno-targets
description	Deploys Uno Platform apps. Per-target guidance for WASM, iOS, Android, macOS, Windows, Linux.
metadata	{"short-description":".NET skill guidance for ui tasks"}

dotnet-uno-targets

Per-target deployment guidance for Uno Platform applications: Web/WASM, iOS, Android, macOS (Catalyst), Windows, Linux (Skia/GTK), and Embedded (Skia/Framebuffer). Each target section covers project setup, debugging workflow, packaging/distribution, platform-specific gotchas, AOT/trimming implications, and behavior differences from other targets.

Scope

• Per-target project setup: WASM, iOS, Android, macOS (Catalyst), Windows, Linux, Embedded
• Debugging workflow per target platform
• Packaging and distribution (App Store, Play Store, MSIX, Flatpak)
• Platform-specific gotchas and AOT/trimming implications

Out of scope

• Core Uno Platform development (Extensions, MVUX, Toolkit) -- see [skill:dotnet-uno-platform]
• MCP integration for live docs -- see [skill:dotnet-uno-mcp]
• Uno Platform testing -- see [skill:dotnet-uno-testing]
• General AOT/trimming patterns -- see [skill:dotnet-aot-wasm]
• UI framework selection -- see [skill:dotnet-ui-chooser]

Cross-references: [skill:dotnet-uno-platform] for core development, [skill:dotnet-uno-mcp] for MCP integration, [skill:dotnet-uno-testing] for testing, [skill:dotnet-aot-wasm] for general WASM AOT patterns, [skill:dotnet-ui-chooser] for framework selection.

---

Target Platform Overview

Target	TFM	Tooling	Packaging	Key Constraints
Web/WASM	net8.0-browserwasm	Browser DevTools	Static hosting / Azure SWA	No filesystem access, AOT recommended, limited threading
iOS	net8.0-ios	Xcode / VS Code / Rider	App Store / TestFlight	Provisioning profiles, entitlements, no JIT
Android	net8.0-android	Android SDK / Emulator	Play Store / APK sideload	SDK version targeting, permissions
macOS (Catalyst)	net8.0-maccatalyst	Xcode	Mac App Store / notarization	Sandbox restrictions, entitlements
Windows	net8.0-windows10.0.19041	Visual Studio	MSIX / Windows Store	WinAppSDK version alignment
Linux	net8.0-desktop	Skia/GTK host	AppImage / Flatpak / Snap	GTK dependencies, Skia rendering
Embedded	net8.0-desktop	Skia/Framebuffer	Direct deployment	No windowing system, headless rendering

TFM note: Use version-agnostic globs (net*-ios, net*-android) when detecting platform targets programmatically to avoid false negatives on older or newer TFMs.

---

Web/WASM

Project Setup

# Run the WASM target
dotnet run -f net8.0-browserwasm --project MyApp/MyApp.csproj

```bash

The WASM target renders XAML controls in the browser. The renderer depends on project configuration: Skia (canvas/WebGL) or native HTML mapping. The app loads via a JavaScript bootstrap (`uno-bootstrap.js`) that initializes the .NET WASM runtime.

### Debugging

- **Browser DevTools:** Use F12 in Chrome/Edge to inspect DOM, network, console output
- **.NET debugging:** Visual Studio and VS Code support debugging the .NET WASM runtime via browser CDP
- **Uno DevServer:** `dotnet run` starts a development server with live reload support
- **Console logging:** `ILogger` output appears in the browser console

### Packaging/Distribution

```bash

# Publish for production
dotnet publish -f net8.0-browserwasm -c Release --output ./publish

# Output is a static site (HTML/JS/WASM)
# Deploy to: Azure Static Web Apps, GitHub Pages, Netlify, any static host

```text

Published output is a self-contained static site. No server-side runtime required.

### Platform Gotchas

- **No filesystem access:** Use browser storage APIs (IndexedDB, localStorage) via JS interop or Uno.Storage
- **Threading limitations:** Web Workers provide limited multi-threading; `Task.Run` may not parallelize on WASM
- **CORS restrictions:** HTTP requests from WASM are subject to browser CORS policy
- **Initial load time:** The .NET WASM runtime and assemblies must download before the app is usable. Use assembly trimming to reduce download size. AOT improves runtime execution speed but increases artifact size
- **Deep linking:** Configure URL routing in the Uno Navigation Extensions for browser URL bar navigation

### AOT/Trimming

**Trimming** reduces download size by removing unused code. **AOT** pre-compiles IL to WebAssembly, improving runtime execution speed but increasing artifact size. Use both together and measure the tradeoffs for your app.

```xml

<PropertyGroup Condition="'$(TargetFramework)' == 'net8.0-browserwasm'">
  <WasmShellMonoRuntimeExecutionMode>InterpreterAndAOT</WasmShellMonoRuntimeExecutionMode>
  <RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>

```bash

**Trimming is critical for WASM.** Untrimmed apps can exceed 30MB. With trimming, typical apps are 5-15MB. AOT adds to the artifact size but eliminates interpreter overhead at runtime -- profile both download  and execution speed  target conditions.

For Uno-specific AOT gotchas (linker descriptors, Uno  generators), see the AOT section. For general WASM AOT patterns, see [skill:dotnet-aot-wasm].



- **Navigation:** URL-based deep linking works natively; route maps should define URL patterns
- **Authentication:** OAuth flows use browser redirects (popup or redirect); no native browser available. Token storage uses browser secure storage
- **Debugging:** Full .NET debugger available via CDP; breakpoints work  Visual Studio/VS Code
- **File pickers:** Use browser file input APIs; `FileOpenPicker` maps to `<input =>`

---





```bash


dotnet build -f net8.0-ios


dotnet run -f net8.0-ios

```text

Requires Xcode installed on macOS. The renderer (Skia or native) depends on project configuration and Uno version.



- **Visual Studio (Pair to Mac) / VS Code + C# Dev Kit / Rider:** Attach to iOS simulator or device
- **Xcode Instruments:** Profile CPU, memory, and energy usage
- **Hot Reload:** Supported via `DOTNET_MODIFIABLE_ASSEMBLIES=debug`



```bash


dotnet publish -f net8.0-ios -c Release \
  /p:CodesignKey= \
  /p:CodesignProvision=

```text

Distribution channels: App Store (requires Apple Developer account), TestFlight (beta testing), Ad Hoc (enterprise).

**Required:** Provisioning profiles, signing certificates, entitlements file  capabilities (push notifications, HealthKit, etc.).



- **No JIT compilation:** iOS prohibits JIT. All code must be AOT-compiled or interpreted. The .NET runtime uses the Mono interpreter by default
- **Provisioning profiles:** Must match bundle ID, team ID, and entitlements. Expired profiles cause cryptic build failures
- **Background execution:** iOS restricts background processing. Use `BGTaskScheduler`  background work
- **App Transport Security (ATS):** HTTPS required by default; HTTP requires an `NSAppTransportSecurity` exception  `Info.plist`
- **Memory pressure:** iOS aggressively kills background apps. Handle `MemoryWarning` events



iOS requires AOT by default (no JIT). The .NET runtime compiles to native ARM64 code.

```xml

<PropertyGroup Condition=>
  <PublishTrimmed></PublishTrimmed>
  <TrimMode></TrimMode>
</PropertyGroup>

```text

**Gotcha:** Reflection-heavy code fails silently on iOS. Test with trimming enabled during development, not just  release builds.



- **Navigation:** Gesture-based back navigation (swipe from left edge) is automatic with Uno Navigation
- **Authentication:** Uses `ASWebAuthenticationSession`  OAuth; biometric auth via `LocalAuthentication` framework
- **Debugging:** Simulator is fast; device debugging requires USB connection and provisioning. Remote debugging with Hot Reload supported

---





```bash


dotnet build -f net8.0-android


dotnet run -f net8.0-android

```text

Requires Android SDK (installed via `dotnet workload install android` or Android Studio).



- **Android Emulator:** Use Android Studio$(TargetFramework)androids single-window model may need adaptation  multi-window scenarios



Same profile as iOS (AOT by default  Catalyst). Trimming recommended  distribution builds.



- **Navigation:** No swipe-back gesture; relies on toolbar back button or keyboard shortcuts (Cmd+[)
- **Authentication:** Uses `ASWebAuthenticationSession` (shared with iOS); supports Touch ID via Secure Enclave
- **Debugging:** Native macOS process; standard .NET debugging tools work. No simulator -- runs as native app

---





```bash


dotnet build -f net8.0-windows10.0.19041


dotnet run -f net8.0-windows10.0.19041

```text

The Windows target can use either the Skia renderer or native WinAppSDK/WinUI 3 rendering.



- **Visual Studio:** Full debugging with XAML Hot Reload, Live Visual Tree, Live Property Explorer
- **WinUI diagnostics:** Built- diagnostic overlay  layout inspection



```bash


dotnet publish -f net8.0-windows10.0.19041 -c Release \
  /p:PackageOutputPath=./packages

```bash

Distribution: Microsoft Store (MSIX), sideloading (MSIX with certificate), ClickOnce, or direct EXE.



- **WinAppSDK version alignment:** The Windows TFM version must match the minimum Windows version. `10.0.19041` = Windows 10 2004+
- **UAC and elevation:** Apps cannot self-elevate. Design  standard user permissions
- **Windows-specific APIs:** `Windows.Storage`, `Windows.Networking` APIs are available only on Windows target. Use conditional compilation or Uno abstractions
- **MSIX signing:** MSIX packages must be signed  installation. Use a code signing certificate  distribution



```xml

<PropertyGroup Condition=>
  <PublishTrimmed></PublishTrimmed>
  <PublishAot></PublishAot>
</PropertyGroup>

```text

Windows supports both JIT and AOT. AOT produces a single native EXE with faster startup.



- **Navigation:** Standard Windows navigation (Alt+Left  back, title bar back button)
- **Authentication:** Uses system browser or WAM (Web Account Manager)  SSO with Microsoft accounts
- **Debugging:** Richest debugging experience with Visual Studio Live Visual Tree and XAML Hot Reload

---





```bash


dotnet build -f net8.0-desktop


dotnet run -f net8.0-desktop

```text

The Linux target uses the Skia renderer with a GTK host window. All XAML rendering is  by Skia -- GTK provides only the window and input handling.



- **VS Code with C# Dev Kit:** Remote debugging on Linux
- **JetBrains Rider:** Full Linux debugging support
- **Console logging:** `dotnet run` outputs logs to terminal



```bash


dotnet publish -f net8.0-desktop -c Release \
  --self-contained \
  -r linux-x64



```text

Distribution: AppImage (portable, no install), Flatpak (sandboxed), Snap (Ubuntu Store), DEB/RPM packages.



- **GTK dependencies:** The app requires GTK3 libraries at runtime. Package or document the dependency: `libgtk-3-0`, `libskia*`
- **Skia rendering:** All rendering is Skia-based. Native GTK widgets are not used. This ensures pixel-perfect cross-platform rendering but means the app does not follow the host GTK theme
- **Font rendering:** Ensure fonts are available on the target system. Embed fonts  the app or  font dependencies
- **Display scaling:** HiDPI support works via Skia;  with `GDK_SCALE=2` environment variable



```xml

<PropertyGroup Condition=>
  <PublishTrimmed></PublishTrimmed>
  <PublishAot></PublishAot>
</PropertyGroup>

```text

AOT on Linux produces a native binary. Self-contained deployment avoids requiring a system-wide .NET runtime.



- **Navigation:** Keyboard-driven (Alt+Left  back). No gesture-based navigation
- **Authentication:** Uses system browser  OAuth flows. No platform-specific auth APIs
- **Debugging:** Standard .NET debugging. No platform-specific debugger tools

---





The Embedded target uses the Skia renderer with a framebuffer backend, enabling headless or kiosk-style rendering without a windowing system.

```bash


dotnet build -f net8.0-desktop -r linux-arm64


dotnet run -f net8.0-desktop

```text

The embedded target shares the `net8.0-desktop` TFM with Linux desktop. Platform-specific configuration selects the framebuffer backend.

```csharp

// Program.cs -- framebuffer host configuration
public static void Main(string[] args)
{
    SkiaHostBuilder.Create()
        .UseFrameBuffer()  // Use framebuffer instead of GTK
        .App(() => new App())
        .Build()
        .Run();
}

```text



- **SSH remote debugging:** Use VS Code Remote or `dotnet-trace`  remote profiling
- **Serial console:** Redirect logs to serial output  headless debugging
- **Remote logging:** Configure Serilog with network sink  remote  aggregation



```bash


dotnet publish -f net8.0-desktop -c Release \
  --self-contained \
  -r linux-arm64


scp -r ./publish/* pi@device:/opt/myapp/

```text

Direct deployment to device filesystem. No app store or package manager.



- **No windowing system:** No X11/Wayland. The app renders directly to the Linux framebuffer (`/dev/fb0`)
- **Input handling:** Touch input via Linux input events (`/dev/input/event*`). No mouse cursor by default
- **Limited resources:** Embedded devices often have constrained RAM and CPU. Profile memory usage carefully
- **No browser:** OAuth flows that require a browser are not available. Use device-code flow or pre-provisioned tokens
- **Display resolution:** Must match the framebuffer resolution. Set via kernel boot parameters or `fbset`



**AOT is strongly recommended  embedded** due to limited resources and startup  requirements.

```xml

<PropertyGroup Condition=>
  <PublishTrimmed></PublishTrimmed>
  <PublishAot></PublishAot>
  <InvariantGlobalization></InvariantGlobalization>
</PropertyGroup>

```text

`InvariantGlobalization` reduces binary size by removing ICU data (~28MB). Only use  the app does not need locale-specific formatting.



- **Navigation:** Touch or hardware button only. No keyboard shortcuts or gesture bars
- **Authentication:** Device-code flow or pre-provisioned credentials. No browser-based OAuth
- **Debugging:** Remote only. No  IDE. Use SSH debugging or remote logging

---





| Target | Back Navigation | Deep Linking | Gesture Navigation |
|--------|----------------|--------------|-------------------|
| Web/WASM | Browser back button / Alt+Left | URL-based routing | None |
| iOS | Swipe from left edge | URL schemes / Universal Links | Full gesture support |
| Android | Hardware/software back button | Intent filters / App Links | System back gesture (Android 13+) |
| macOS | Cmd+[ / toolbar back | URL schemes | None |
| Windows | Alt+Left / title bar back | Protocol activation | None |
| Linux | Alt+Left / keyboard | None | None |
| Embedded | Hardware button only | None | Touch only |



| Target | OAuth Flow | Token Storage | Biometric |
|--------|-----------|---------------|-----------|
| Web/WASM | Browser redirect/popup | Browser secure storage | WebAuthn (limited) |
| iOS | `ASWebAuthenticationSession` | Keychain | Touch ID / Face ID |
| Android | Chrome Custom Tabs | Android Keystore | BiometricPrompt |
| macOS | `ASWebAuthenticationSession` | Keychain | Touch ID |
| Windows | System browser / WAM | Credential Manager | Windows Hello |
| Linux | System browser | Secret Service API | None |
| Embedded | Device-code flow | File-based (encrypt) | None |



| Target | IDE Debugger | Hot Reload | Profiling |
|--------|-------------|-----------|-----------|
| Web/WASM | VS / VS Code (CDP) | Yes | Browser DevTools |
| iOS | VS (Pair to Mac) / VS Code / Rider | Yes | Xcode Instruments |
| Android | VS / VS Code | Yes | Android Profiler |
| macOS | VS (Pair to Mac) / VS Code / Rider | Yes | Xcode Instruments |
| Windows | Visual Studio | Yes (+ Live Visual Tree) | VS Diagnostic Tools |
| Linux | VS Code / Rider | Yes | dotnet-counters / dotnet-trace |
| Embedded | VS Code Remote | Yes (SSH) | dotnet-trace (remote) |

---



1. **Do not hardcode TFM versions  detection logic.** Use version-agnostic globs (`net*-ios`, `net*-android`) to handle both .NET 8 and future .NET versions.
2. **Do not assume all targets share the same debugging workflow.** iOS requires provisioning; Android requires ADB; WASM uses browser DevTools. Each target has distinct tooling.
3. **Do not use JIT-dependent patterns on iOS.** iOS prohibits JIT compilation. Code that uses `Reflection.Emit`, `Expression.Compile()`, or dynamic assembly loading will fail at runtime.
4. **Do not forget platform-specific permissions.** Android runtime permissions, iOS entitlements, macOS sandbox permissions, and WASM CORS policy are all different and must be handled per-target.
5. **Do not deploy untrimmed WASM apps.** Untrimmed WASM bundles exceed 30MB. Always  trimming and consider AOT  production WASM deployments.
6. **Do not assume file system access on all targets.** WASM has no filesystem; iOS/macOS have sandbox restrictions; embedded may have read-only storage. Use Uno Storage abstractions.
7. **Do not use the same authentication flow  all targets.** WASM uses browser redirects, mobile uses native auth sessions, embedded uses device-code flow. Auth must be configured per-target.

---



- .NET 8.0+ with platform workloads: `dotnet workload install ios android maccatalyst wasm-tools`
- Platform SDKs: Xcode (iOS/macOS), Android SDK (Android), GTK3 (Linux)
- Uno Platform 5.x+

---



- [Uno Platform Getting Started](https://platform.uno/docs/articles/get-started.html)
- [Uno Platform Targets](https://platform.uno/docs/articles/getting-started/requirements.html)
- [WASM Deployment](https://platform.uno/docs/articles/features/using-il-linker-webassembly.html)
- [iOS Deployment](https://learn.microsoft.com/en-us/dotnet/maui/ios/deployment/)
- [Android Deployment](https://learn.microsoft.com/en-us/dotnet/maui/android/deployment/)
- [Linux with Skia/GTK](https://platform.uno/docs/articles/get-started-with-linux.html)

Code Navigation (Serena MCP)

Primary approach: Use Serena symbol operations for efficient code navigation:

1. Find definitions: serena_find_symbol instead of text search
2. Understand structure: serena_get_symbols_overview for file organization
3. Track references: serena_find_referencing_symbols for impact analysis
4. Precise edits: serena_replace_symbol_body for clean modifications

When to use Serena vs traditional tools:

• Use Serena: Navigation, refactoring, dependency analysis, precise edits
• Use Read/Grep: Reading full files, pattern matching, simple text operations
• Fallback: If Serena unavailable, traditional tools work fine

Example workflow:

# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"

# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"