MicrosoftDocs
diff --git a/‎hub/apps/desktop/modernize/framework-packages/framework-packages-overview.md
Lines changed: 55 additions & 0 deletions b/‎hub/apps/desktop/modernize/framework-packages/framework-packages-overview.md
Lines changed: 55 additions & 0 deletions
diff --git a/‎hub/apps/desktop/modernize/framework-packages/index.md
Lines changed: 27 additions & 0 deletions b/‎hub/apps/desktop/modernize/framework-packages/index.md
Lines changed: 27 additions & 0 deletions
diff --git a/‎hub/apps/desktop/modernize/framework-packages/use-the-dynamic-dependency-api.md
Lines changed: 90 additions & 0 deletions b/‎hub/apps/desktop/modernize/framework-packages/use-the-dynamic-dependency-api.md
Lines changed: 90 additions & 0 deletions
@@ -0,0 +1,55 @@
+---
+description: Learn about the package graph and servicing model for MSIX framework packages.
+title: MSIX framework packages and dynamic dependencies
+ms.topic: article
+ms.date: 07/30/2021
+ms.localizationpriority: medium
+---
+
+# MSIX framework packages and dynamic dependencies
+
+This article introduces important concepts related to *MSIX framework packages*. The information in this article provides useful context to help you better understand the design and purpose of the *dynamic dependencies* feature in the Windows App SDK and in the Windows 11 OS. This feature enables your apps to reference and use MSIX framework packages at run time.
+
+## Framework packages and the package graph
+
+[MSIX](/windows/msix) is a package format that provides a modern packaging and deployment experience. It also provides a clean and trusted way to package redistributable libraries, content and components via *MSIX framework packages*. An MSIX framework package allows MSIX-packaged apps to access components through a single shared source on the user's device, instead of bundling them into the app package. Common framework packages include the [Windows App SDK](../../../windows-app-sdk/index.md) (including WinUI3), [WinUI2](../../../winui/winui2/index.md), [VCLibs](/troubleshoot/cpp/c-runtime-packages-desktop-bridge), and the DirectX Runtime.
+
+Starting in Windows 8 and continuing through Windows 10 and Windows 11, every process has a *package graph* that provides the list of all the packages available to the app, including framework, resource, optional, and main packages. This graph allows the app to load DLLs, content, and run-time class declarations provided by a referenced package. Historically, this graph was fixed at process creation time, and there was no way to alter it at run time:
+
+- For MSIX-packaged apps, the graph was initialized based on the package dependencies declared in the [PackageDependency](/uwp/schemas/appxpackage/uapmanifestschema/element-packagedependency) element in the app's package manifest. When building a packaged app, this was typically done for you during the build process based on your project references and dependencies.
+- For unpackaged apps (that is, apps that do not use MSIX for their deployment technology), the package graph was empty and could not be changed. Therefore, unpackaged apps were limited to [standard DLL search order](/windows/win32/dlls/dynamic-link-library-search-order) and could not access framework packages.
+
+This static package graph restriction is lifted with the introduction of the dynamic dependencies support in both the [Windows App SDK](../../../windows-app-sdk/index.md) and in Windows 11. Developers can use dynamic dependencies to reference and use MSIX framework packages from their apps at run time. Dynamic dependencies removes the static package graph restriction from apps, and developers can decide how they want to leverage framework packages.
+
+## Primary scenarios for dynamic dependencies
+
+Although dynamic dependencies enables any app to add a package framework dependency at run time, this feature is primarily intended to be used by unpackaged apps. Packaged apps can still continue to add static dependencies via the [PackageDependency](/uwp/schemas/appxpackage/uapmanifestschema/element-packagedependency) element in their package manifest.
+
+- Most developers will only use dynamic dependencies to reference the [Windows App SDK](../../../windows-app-sdk/index.md) framework package in an unpackaged app so that the app can call APIs provided by the Windows App SDK runtime. For more information about this scenario, see [Reference the Windows App SDK framework package at run time](../../../windows-app-sdk/reference-framework-package-run-time.md).
+- In some cases, developers may want to use dynamic dependencies to reference a different framework package (other than the Windows App SDK framework package) from an unpackaged app, such as the framework package for [WinUI2](../../../winui/winui2/index.md) or the DirectX Runtime. For more information about this scenario, see [Reference framework packages at run time](use-the-dynamic-dependency-api.md).
+
+## Servicing model for framework packages
+
+The dynamic dependencies feature preserves the integrity of the servicing pipeline for the framework package that is being referenced and used dynamically at run time.
+
+MSIX framework packages support servicing in a side-by-side model, meaning each version is installed in its own separate versioned folder. This allows applications in use to be able to stay up and running even when a newer app installs a newer version of the framework package. The OS has uninstall logic for when to delete older versions of a given framework package, based on the presence of *install-time references* and *run-time references* for the package.
+
+- When an app is installed, it can create an *install-time reference* to a framework package. This reference informs the OS that the app has a dependency upon the specified framework package so that the OS won't uninstall the framework package while your app is installed.
+- When an app needs to use APIs or content in a framework package, it can add a *run-time reference* to the framework package. This reference informs the OS that the framework package is in active use and to handle any version updates in a side-by-side manner. If a new version of the framework package is installed, but a running app has an older version in use, the OS cannot remove the older version until all run-time references to the older version are removed.
+
+For example, given this scenario:
+
+- **App A** is running and using version 1.0.0.0 of a given framework package.
+- **App B** is installed and has a dependency upon version 1.0.0.1 of the same framework package.
+
+In this scenario, both versions of the framework package will be installed and in use by **App A** and **App B**. However, when **App A** is closed by the user and then restarted, it will pick up the newer version 1.0.0.1 of the framework package. At this point, the run-time reference requirement is no longer valid for version 1.0.0.0 of the framework package, and the OS can safely remove the 1.0.0.0 version. Later, when **App A** and **App B** are uninstalled by the user, then the install-time reference requirement is no longer valid and it is safe for the OS to remove the framework package entirely.  
+
+For MSIX-packaged apps that use the [PackageDependency](/uwp/schemas/appxpackage/uapmanifestschema/element-packagedependency) element to specify static references to framework packages, the install-time references for framework packages are tracked by the OS when the app is installed or uninstalled. For run-time references that are managed by using the dynamic dependencies feature, the OS knows when a packaged app is running and will avoid removing its in-use framework packages when a newer one is available.
+
+## Related topics
+
+- [Reference the Windows App SDK framework package at run time](../../../windows-app-sdk/reference-framework-package-run-time.md)
+- [Use the dynamic dependency API to reference framework packages at run time](use-the-dynamic-dependency-api.md)
+- [Deploy unpackaged apps that use the Windows App SDK](../../../windows-app-sdk/deploy-unpackaged-apps.md)
+- [Run time architecture and deployment scenarios for the Windows App SDK](../../../windows-app-sdk/deployment-architecture.md)
+- [Tutorial: Build and deploy an unpackaged app that uses the Windows App SDK](/windows/apps/windows-app-sdk/tutorial-unpackaged-deployment)
@@ -0,0 +1,27 @@
+---
+description: Learn about using MSIX framework packages dynamically from your desktop app.
+title: Use MSIX framework packages dynamically from your desktop app
+ms.topic: article
+ms.date: 07/30/2021
+ms.localizationpriority: medium
+---
+
+# Use MSIX framework packages dynamically from your desktop app
+
+The [Windows App SDK](../../../windows-app-sdk/index.md) and the Windows 11 OS both enable your apps to reference and use [MSIX framework packages](framework-packages-overview.md) dynamically at run time by using a feature called *dynamic dependencies*. This feature is intended to be used primarily by unpackaged desktop apps (that is, apps that do not use MSIX for their deployment technology) to use APIs and other content provided by MSIX framework packages.
+
+The most common scenario for using the dynamic dependencies feature is to reference the [Windows App SDK](../../../windows-app-sdk/index.md) framework package in an unpackaged app. In some scenarios, you may want to use the dynamic dependencies feature to reference a different framework package from an unpackaged app, such as the framework package for [WinUI2](../../../winui/winui2/index.md) or the DirectX Runtime.
+
+For an overview of the dynamic dependencies feature and guidance about using it in your apps, see the following articles.
+
+| Article | Description |
+|---------|-------------|
+|  [MSIX framework packages and dynamic dependencies](framework-packages-overview.md) | Introduces important concepts related to MSIX framework packages and describes the purpose of dynamic dependencies feature. This article includes details about the package graph for framework package references and the servicing model for framework packages. |
+|  [Reference the Windows App SDK framework package at run time](../../../windows-app-sdk/reference-framework-package-run-time.md) | Describes how to use the *bootstrapper API* to dynamically take a dependency on the Windows App SDK framework package in an unpackaged app at run time. This scenario enables unpackaged apps to use Windows App SDK features.   |
+|  [Reference framework packages at run time](use-the-dynamic-dependency-api.md) | Describes how to use the *dynamic dependency API* to dynamically take a dependency on different framework packages (other than the Windows App SDK framework package) in an unpackaged app at run time. |
+
+## Related topics
+
+- [Deploy unpackaged apps that use the Windows App SDK](../../../windows-app-sdk/deploy-unpackaged-apps.md)
+- [Runtime architecture and deployment scenarios for the Windows App SDK](../../../windows-app-sdk/deployment-architecture.md)
+- [MSIX documentation](/windows/msix)
@@ -0,0 +1,90 @@
+---
+description: Learn about how to use the dynamic dependency API.
+title: Use the dynamic dependency API to reference framework packages at run time
+ms.topic: article
+ms.date: 07/30/2021
+ms.localizationpriority: medium
+---
+
+# Use the dynamic dependency API to reference framework packages at run time
+
+The *dynamic dependency API* enables unpackaged apps (that is, apps that do not use MSIX for their deployment technology) to reference and use framework packages other than the Windows App SDK framework package. For example, you might use the dynamic dependency API to reference and use the framework package for [WinUI2](../../../winui/winui2/index.md) or the DirectX Runtime in your unpackaged app.
+
+For background information about this scenario, see [MSIX framework packages and dynamic dependencies](framework-packages-overview.md).
+
+> [!NOTE]
+> If you only want to reference the [Windows App SDK](../../../windows-app-sdk/index.md) framework package in your unpackaged app, use the *bootstrapper API* provided by the Windows App SDK instead of the dynamic dependency API. The bootstrapper API is a specialized form of the dynamic dependency API that is designed to take dependencies on the Windows App SDK framework package. After your unpackaged app uses the bootstrapper API to take a dependency on the Windows App SDK framework package, your app can then use APIs provided by the Windows App SDK (including using the dynamic dependency API implementation in the Windows App SDK to take dependencies on other framework packages). For more information about the bootstrapper API, see [Reference the Windows App SDK framework package at run time](../../../windows-app-sdk/reference-framework-package-run-time.md).
+
+## Overview
+
+The dynamic dependency API provides ways to manage the install-time references and run-time references for a framework package. For more information about these types of references, see [Servicing model for framework packages](framework-packages-overview.md#servicing-model-for-framework-packages).
+
+There are two implementations of the dynamic dependency API that you can choose from, depending on your target platform and scenario:
+
+- The Windows App SDK provides both C/C++ functions and WinRT types that implement the dynamic dependency API. This implementation of the API can be used by apps that target Windows 10 version 1809 and later as well as Windows 11, but it has [some limitations](#dynamic-dependency-api-limitations-in-the-windows-app-sdk).
+- Windows 11 also provides C/C++ functions that implement the dynamic dependency API. This implementation of the API can be used only by apps that target Windows 11.
+
+For more details about the dynamic dependency API, see the [dynamic dependencies specification](https://github.com/microsoft/WindowsAppSDK/blob/main/specs/dynamicdependencies/DynamicDependencies.md) on GitHub.
+
+## How to use the dynamic dependency API
+
+To use the dynamic dependency API in your unpackaged app to take a dependency on a framework package, follow this general pattern in your code.
+
+### 1. Create an install-time reference
+
+In your app's installer or during the first run of your app, call one of the following functions or methods to specify a set of criteria for the framework package you want to use. This informs the OS that your app has a dependency upon a framework package that meets the specified criteria. If one or more framework packages are installed that meet the criteria, Windows will ensure that at least one of these framework packages will remain installed until the install-time reference is deleted.
+
+- Windows 11 (C/C++): **TryCreatePackageDependency**
+- Windows App SDK (C/C++): **MddTryCreatePackageDependency**
+- Windows App SDK (WinRT): **Microsoft.Windows.ApplicationModel.DynamicDependency.Create**
+
+The criteria you specify includes the package family name, minimum version, and architectures, but you cannot indicate a specific framework package. When you add a run-time reference to the framework package, the API chooses the highest version that satisfies the specified criteria.
+
+You must also specify a *lifetime artifact*, which can be the current process, a file, or a registry key that indicates to the system that the app is still available. If the specified artifact no longer exists, the OS can assume the dependency is no longer needed and it can uninstall the framework package if no other apps have declared a dependency on it. This feature is useful for scenarios where an app neglects to remove the install-time pin when it is uninstalled.
+
+This API returns a dependency ID that must to be used in other calls to create run-time references and to delete the install-time reference.
+
+### 2. Add a run-time reference
+
+When your app needs to use the framework package, call one of the following functions or methods to request access to the specified framework package and add a run-time reference for it. Calling this API informs the OS that the framework package is in active use and to handle any version updates in a side-by-side manner (effectively delay uninstalling or otherwise servicing the older version until after the app is done using it). If successful, the app may activate classes and use content from the framework package.
+
+- Windows 11 (C/C++): **AddPackageDependency**
+- Windows App SDK (C/C++): **MddAddPackageDependency**
+- Windows App SDK (WinRT): **Microsoft.Windows.ApplicationModel.DynamicDependency.Add**
+
+When you call this API, you must pass in the dependency ID that was returned when you created the install-time reference and the desired rank to use for the framework package in the process's package graph. This API returns the full name of the framework package that was referenced, and a handle that is used to keep track of the active-use dependency. If there are multiple framework packages installed that meet the criteria that you specified when you created the install-time reference, the API chooses highest version that satisfies the criteria.
+
+### 3. Remove the run-time reference
+
+When your app is done using the framework package, call one of the following functions or methods to remove the run-time reference. Typically, your app will call this API during shut down. This API informs the OS that it is safe to remove any unnecessary versions of the framework package.
+
+- Windows 11 (C/C++): **RemovePackageDependency**
+- Windows App SDK (C/C++): **MddRemovePackageDependency**
+- Windows App SDK (WinRT): **Microsoft.Windows.ApplicationModel.DynamicDependency.Remove**
+
+When you call this API, you must pass in the handle that was returned when you added the run-time reference.
+
+### 4. Delete the install-time reference
+
+When your app is uninstalled, call one of the following functions or methods during unto delete the install-time reference. This API informs the OS that it is safe to remove the framework package if no other apps have a dependency on it.
+
+- Windows 11 (C/C++): **DeletePackageDependency**
+- Windows App SDK (C/C++): **MddDeletePackageDependency**
+- Windows App SDK (WinRT): **Microsoft.Windows.ApplicationModel.DynamicDependency.Delete**
+
+When you call this API, you must pass in the dependency ID that was returned when you created the install-time reference.
+
+## Dynamic dependency API limitations in the Windows App SDK
+
+When you use the dynamic dependency API in the Windows App SDK to take a dependency on a framework package, this API requires help via another installed package and running process to inform Windows that the framework package is in use and to block servicing the framework while it is being used. This is called a *lifetime manager* component.
+
+The Windows App SDK provides a lifetime manager component for its framework package called the [Dynamic Dependency Lifetime Manager (DDLM)](../../../windows-app-sdk/deployment-architecture.md#dynamic-dependency-lifetime-manager-ddlm). However, no other framework packages currently provide a similar lifetime manager component from Microsoft.
+
+The dynamic dependency API implementation in Windows 11 does not have this limitation.
+
+## Related topics
+
+- [MSIX framework packages](framework-packages-overview.md)
+- [Dynamic dependencies specification](https://github.com/microsoft/WindowsAppSDK/blob/main/specs/dynamicdependencies/DynamicDependencies.md)
+- [Runtime architecture and deployment scenarios for the Windows App SDK](../../../windows-app-sdk/deployment-architecture.md)
+- [Reference the Windows App SDK framework package at run time](../../../windows-app-sdk/reference-framework-package-run-time.md)