DOCSEARCHbyAlgolia
Submit Docs

Windows App SDK Documentation

repository·main·Indexed 26 days ago

https://github.com/microsoft/windowsappsdk

A collection of libraries, frameworks, and tools enabling developers to use modern Windows APIs and WinUI 3 across Win32, WPF, and WinForms applications. Supports Windows 10 version 1809 and later. Includes documentation on Storage Pickers, MRT Core for resource management, installer insights flow, and packaging via Microsoft.Windows.SDK.BuildTools.MSIX.

Tokens
123.9K
Snippets
219
Records
493
Agent score
88%

What's inside Windows App SDK

  1. Overview of MRT Core

    main
    MRT Core (formerly Core MRT) is a component of the Windows App SDK that provides Modern Resource Technology (MRT) support. It enables developers to build resources into Package Resource Index (PRI) files and load resources from those PRI files, facilitating modern resource management.

  2. Overview of MSIX Package Management APIs

    main

    The Windows App SDK provides enhanced MSIX package management APIs in the Microsoft.Windows.Management.Deployment.PackageDeploymentManager namespace. These APIs are designed to improve upon the legacy Windows.Management.Deployment namespace by offering better developer experience, performance optimizations, and support for modern deployment patterns.

    Key capabilities include:

    • Deployment: Staging, registering, adding, updating, removing, repairing, resetting, provisioning, and deprovisioning packages.
    • Readiness Checks: Verifying if a package is installed, registered, and healthy (Is*Ready) or if a newer version is available (Is*ReadyOrNewerAvailable).
    • Batch Operations: Using PackageSet for batch operations and PackageRuntimeManager for runtime batch operations via Dynamic Dependencies.
    • Validation: Validating package identity and signatures before staging/adding.

  3. Overview of MSIX Dynamic Dependencies

    main

    MSIX Dynamic Dependencies allow both packaged and unpackaged applications to access Framework package content (including WinRT APIs and 'flat C' exports) at runtime.

    This feature supplements the static dependency support provided by <PackageDependency> in appxmanifest.xml by providing a dynamic runtime equivalent. It enables developers to define Framework dependencies based on runtime factors such as machine state or user interface, rather than being limited to development-time definitions.

  4. Overview of Microsoft.Windows.Storage.Pickers

    main

    The Microsoft.Windows.Storage.Pickers namespace provides a modernized file and folder picker experience for WinAppSDK and WinUI 3 desktop applications. Unlike the legacy UWP Windows.Storage.Pickers API, this version is designed specifically for desktop scenarios with the following key improvements:

    • Elevated Process Support: Works correctly when the application is running as an administrator.
    • Simplified Window Association: Instead of using WinRT.Interop.InitializeWithWindow, you pass a Microsoft.UI.WindowId directly to the picker's constructor.
    • String-based Results: Returns file and folder paths as strings via PickFileResult and PickFolderResult instead of StorageFile/StorageFolder objects, avoiding storage capability complications.
    • Flexible Filtering: If no FileTypeFilter or FileTypeChoices are specified, the pickers default to showing all files rather than throwing exceptions.
    • State Persistence: Supports SettingsIdentifier to allow pickers to remember user preferences like size and location across sessions.

  5. Overview of Windows App SDK

    main

    Windows App SDK (formerly Project Reunion) is a set of libraries, frameworks, components, and tools designed to provide access to modern Windows platform functionality across various application types. It bridges Win32 native applications with modern API usage techniques.

    Key Features:

    • WinUI 3 Support: Implements Fluent Design for intuitive and accessible user interfaces.
    • Modern Capabilities: Provides modern resource tooling, lifecycle helpers, and startup tasks.
    • Backwards Compatibility: Supports down to Windows 10 version 1809 (build 17763).
    • Wide Platform Support: Compatible with Win32, WPF, WinForms, and more.
    • Flexible Deployment: Does not require MSIX, though MSIX is recommended for reliability and security benefits.

  6. Understand AppLifecycle Rich Activation

    main

    The AppLifecycle component in Windows App SDK provides modern app activation and lifecycle functionality to non-MSIX-packaged (unpackaged) Win32 apps. It abstracts complex activation logic, making UWP-style rich activation available to traditional desktop applications.

    Key features include:

    • Rich activation objects: Access to detailed activation arguments.
    • Selective single/multi-instancing: Control over how many instances of the app run.
    • System state and power notifications: Awareness of device power and state changes.

    Note: In the initial release (v1), these features are specifically designed for unpackaged apps and are not intended for use by UWP or Desktop Bridge apps.

  7. Understand Decimal representation in Windows App SDK

    main

    Windows App SDK provides a common decimal representation to ensure interoperability across different programming languages.

    • Native Languages: For languages with native decimal support (like C# Decimal or Python decimal), it is recommended to use those native types.
    • C++ Support: Windows App SDK provides Microsoft::Windows::Foundation::decimal for C++.
    • Fallback for other languages: For languages without native decimal support (e.g., JavaScript, Rust), Windows App SDK provides the WinRT runtimeclass Microsoft.Windows.Foundation.Decimal. Note that using the WinRT type incurs performance overhead compared to stack-allocated native types.

    The underlying format is based on the Win32 DECIMAL structure: a 96-bit (12-byte) unsigned integer scaled by a power of 10 (scale 0-28).

  8. Understand WinRT Registration Options in Windows App SDK

    main

    Windows App SDK uses manifest-based solutions to provide WinRT types. Depending on your deployment model, you will use one of the following registration methods to resolve an activatable class id (ACID):

    1. MSIX Packages (Option A - Process Package Graph): Uses the appxmanifest.xml within the MSIX package to declare types. This is the optimal solution for performance and reliability.
    2. Self-Contained (Option B - RegFreeWinRT): Uses a SxS (Side-by-Side/Fusion) manifest named application.manifest. This manifest must be compiled into the caller's PE file and defines the ACID and the associated DLL found via LoadLibrary.
    3. Language Projections (Option C): Used by C#/WinRT and C++/WinRT. The projection crawls the filesystem looking for a DLL whose filename matches the ACID's namespace or prefix (e.g., searching for Microsoft.Network.Bluetooth.Connection.dll, then Microsoft.Network.Bluetooth.dll, etc.).

  9. Understand Windows App SDK MSIX Package Roles

    main

    Windows App SDK is distributed as several MSIX packages, each serving a specific role in the runtime environment. Understanding these roles helps in deciding how to implement features like background tasks or brokered access.

    Package Roles

    • Framework Package: The primary API delivery vehicle containing the vast majority of the project code. It supports side-by-side (SxS) behavior, meaning multiple versions can exist on a user's machine simultaneously without conflict.
    • Main Package: Supplements the Framework for functionality that cannot be delivered via the Framework (e.g., Packaged COM, app services, app extensions, background tasks, startup tasks, or ApplicationData).
      • Warning: Main packages do not support side-by-side behavior. Only one Main package per package family can be registered at a time. Updating a Main package requires terminating any running processes from the previous version.
    • Singleton Package: Supplements the Main package for functionality required by a single process spanning all versions of Windows App SDK.
      • Warning: Only the highest version is installed for a user. Content must be backwards compatible across all releases.
    • Dynamic Dependency Lifetime Manager (DDLM): Uses a Packaged COM out-of-process (OOP) server to ensure that the Framework package is recognized as "in use" by Windows, preventing disruptive servicing (like removal or repair) while the app is running.

  10. Use AppLifecycle Environment Variable tracking

    main

    The AppLifecycle component provides a unified set of APIs for managing environment variables across different app types (packaged and unpackaged). A key feature is Environment Variable (EV) tracking, which allows the platform to clean up variables when an app is uninstalled.

    Tracking supports two scenarios:

    1. Variable Creation: If an app creates a new variable, the platform can delete it upon uninstallation.
    2. Variable Modification: If an app modifies an existing variable, the platform can restore the previous value upon uninstallation.

    Compatibility Note: EV tracking requires Windows 21H1 or later (version >= 10.0.19043.0).

  11. Understand Windows App SDK API Contracts

    main
    Windows App SDK uses WinRT API contracts to allow applications to detect available API features at build time and run time. This enables apps to gracefully degrade or enable specific features based on the version of the Windows App SDK installed on the system. Contracts are applied to WinRT APIs to define version boundaries.

  12. Understand Windows App SDK consumption and packaging

    main

    Windows App SDK components are consumed via NuGet packages (at build time) and Framework packages (at runtime).

    • Build Time: Developers add NuGet packages to their build environments to get metadata and language-specific requirements.
    • Runtime: The SDK is delivered as a set of DLLs via a Framework package.
      • Packaged apps depend on the framework package specifically.
      • Unpackaged apps can deploy a WindowsAppSDK.MSIX containing the framework package as part of the app's installer.
    • Framework Packages: These allow multiple apps to share common binaries managed by the system, reducing app size and enabling faster security/reliability updates without requiring app-level updates.