Winui Packaging

Quick Reference

End-to-End Workflow

Step 1: Build for Release

Use the BuildAndRun.ps1 script from the winui-dev-workflow skill to build your app in Release configuration without launching it:

.\BuildAndRun.ps1 /p:Configuration=Release -SkipRun

Step 2: Generate Certificate (one-time)

winapp cert generate --manifest .

Creates devcert.pfx (default password: password). The --manifest flag auto-matches the Publisher field in Package.appxmanifest.

Step 3: Trust Certificate (one-time, requires admin)

winapp cert install ./devcert.pfx

Adds cert to machine Trusted Root store. Persists across reboots.

Step 4: Package and Sign

winapp package <build-output-dir> --cert ./devcert.pfx

This locates appxmanifest.xml, stages the layout, generates resources.pri, creates .msix, and signs it.

Step 5: Install or Distribute

# Local install
Add-AppxPackage ./MyApp.msix

# Or double-click the .msix file

Key Rules

• Publisher must match between certificate and manifest Identity.Publisher — use winapp cert generate --manifest to auto-match
• Prefer `winapp package --cert` over separate winapp sign — one step instead of two
• `cert install` requires admin — run terminal as Administrator
• Default PFX password is password — override with --password
• `--timestamp` is critical for production — without it, signatures expire with the cert:

  winapp package <dir> --cert prod.pfx --timestamp http://timestamp.digicert.com

• `--self-contained` bundles Windows App SDK runtime — larger but no runtime dependency

CI/CD with GitHub Actions

name: Build and Package
on: [push]
jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: microsoft/setup-WinAppCli@v0.1

      - name: Build
        run: dotnet build -c Release -p:Platform=x64

      - name: Package
        run: |
          winapp cert generate --if-exists skip --quiet
          winapp package ./bin/x64/Release/ --cert ./devcert.pfx --quiet

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: msix-package
          path: "*.msix"

CI/CD tips:

• Use --quiet for clean output
• Use --if-exists skip with cert generate to avoid failures on re-runs
• Store production PFX as a repository secret

Store Submission

1. Partner Center account — register at partner.microsoft.com 2. Age ratings — complete the questionnaire in Partner Center 3. Screenshots — capture at 1366x768 minimum resolution 4. Privacy policy — required for apps that access internet or user data 5. Submit: upload the signed .msix / .msixbundle produced by winapp package via Microsoft Partner Center — Apps and games → your app → Packages. Microsoft Store submission is browser-based; there is no first-party CLI submit command yet.

Troubleshooting

References

Source Generator Patterns — Detailed Reference

Detailed code patterns for AOT compilation and source generators. See SKILL.md for rules summary.

---

Trimming Configuration

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <TrimMode>full</TrimMode>
  <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>
</PropertyGroup>

For reflection-heavy code, annotate to preserve members:

public void LoadService([DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] Type serviceType)
    => Activator.CreateInstance(serviceType);

---

Trim Compatibility Testing

Keep warnings enabled during development:

<SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>
<TrimmerSingleWarn>false</TrimmerSingleWarn>

Patterns to eliminate:

• Type.GetType("MyNamespace.MyClass") — use typeof(T) or [DynamicDependency]
• Activator.CreateInstance(someType) without [DynamicallyAccessedMembers]
• Assembly.LoadFrom() — use compile-time references
• Unattributed reflection: typeof(T).GetProperties()

---

JSON Source Generator Setup

[JsonSerializable(typeof(UserProfile))]
[JsonSerializable(typeof(List<UserProfile>))]
internal partial class AppJsonContext : JsonSerializerContext { }

// No reflection at runtime
var json = JsonSerializer.Serialize(profile, AppJsonContext.Default.UserProfile);
var obj = JsonSerializer.Deserialize(json, AppJsonContext.Default.UserProfile);

---

Regex Source Generator

public partial class InputValidator
{
    [GeneratedRegex(@"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")]
    private static partial Regex EmailRegex();
    public bool IsValidEmail(string input) => EmailRegex().IsMatch(input);
}

---

XAML Compilation (x:Bind)

<!-- ✅ AOT-safe: compile-time generated -->
<TextBlock Text="{x:Bind ViewModel.Title, Mode=OneWay}" />

<!-- ❌ Reflection-based, not trim-safe -->
<TextBlock Text="{Binding Path=Title}" />

Set x:DataType on pages: <Page x:DataType="viewmodels:MainViewModel">

---

CsWin32 Setup

Generates P/Invoke wrappers at compile time. Add Microsoft.Windows.CsWin32 NuGet package. List needed APIs in NativeMethods.txt:

GetDpiForWindow
SetWindowPos
ShowWindow

---

CommunityToolkit.Mvvm Source Generators

Use partial properties (CommunityToolkit.Mvvm 8.4+). The legacy field form emits MVVMTK0045 in WinRT/WinUI projects.

public partial class SettingsViewModel : ObservableObject
{
    [ObservableProperty] public partial string UserName { get; set; }
    [RelayCommand] private async Task SaveAsync() => await _service.SaveAsync(UserName);
}

---

Single-File Publishing Configuration

<PropertyGroup>
  <SelfContained>true</SelfContained>
  <PublishSingleFile>true</PublishSingleFile>
  <EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
</PropertyGroup>

Primarily for unpackaged apps. Combine with <PublishTrimmed>true</PublishTrimmed>.