Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This article shows how to configure an unpackaged framework-dependent app to use the Bootstrapper API explicitly. The Bootstrapper adds an installed Windows App SDK Framework package to the process package graph before the app calls APIs from that package.
Packaged apps, including apps packaged with external location (sparse packages), can declare this dependency statically with <PackageDependency> in AppxManifest.xml instead. They don't need Bootstrapper initialization for that dependency. Self-contained apps carry the Framework binaries app-locally and don't need a Framework MSIX dependency or Bootstrapper initialization for those binaries.
Important
For an unpackaged framework-dependent executable, setting <WindowsPackageType>None</WindowsPackageType> enables Bootstrapper auto-initialization by default. For the steps involved in a WinUI 3 project, see Distribute an unpackaged WinUI 3 app. For an existing project that doesn't use WinUI, see Use the Windows App SDK in an existing project.
If you have advanced needs (such as custom error handling, or to load a specific version of the Windows App SDK), then you can instead call the bootstrapper API explicitly. And that's the approach that this topic demonstrates. Also, for more info, see Initialize the Windows App SDK Framework package dynamically.
This topic demonstrates explicitly calling the bootstrapper API from a basic Console app project; but the steps apply to any unpackaged desktop app that uses the Windows App SDK.
Before completing this tutorial, review Runtime architecture to learn how static manifest dependencies, dynamic Bootstrapper dependencies, and self-contained deployment differ.
Prerequisites
- Install tools for the Windows App SDK.
- Install the dependencies for an unpackaged framework-dependent app (see Windows App SDK deployment guide for framework-dependent unpackaged apps). You can do this by running the Windows App SDK runtime installer.
Instructions
You can follow this tutorial using a C# or a C++ project.
Note
The dynamic dependencies and bootstrapper APIs fail when called by an elevated process. As a result, Visual Studio shouldn't be launched elevated. See Dynamic Dependencies doesn't support elevation #567 for more details.
Follow these instructions to configure an unpackaged C# console project for explicit Bootstrapper initialization.
In Visual Studio, create a new C# Console App project. Name the project DynamicDependenciesTest. After you create the project, you should have a "Hello, World!" C# console app.
Next, configure your project.
- In Solution Explorer, right-click your project and choose Edit Project File.
- Replace the value of the TargetFramework element with a Target Framework Moniker. For example, use the following if your app targets Windows 10, version 2004.
<TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>- In the same
PropertyGroupin the.csprojfile, identify the project as unpackaged and disable automatic Bootstrapper initialization so that the sample controls initialization and shutdown.
<WindowsPackageType>None</WindowsPackageType> <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize>- Save and close the project file.
Change the platform for your solution to x64. The default value in a .NET project is AnyCPU, but WinUI doesn't support that platform.
- Select Build > Configuration Manager.
- Select the drop-down under Active solution platform and click New to open the New Solution Platform dialog box.
- In the drop-down under Type or select the new platform, select x64.
- Click OK to close the New Solution Platform dialog box.
- In Configuration Manager, click Close.
Install the Windows App SDK NuGet package in your project.
- In Solution Explorer, right-click the Dependencies node and choose Manage Nuget Packages.
- In the NuGet Package Manager window, select the Browse tab, and install the Microsoft.WindowsAppSDK package.
You're now ready to use the bootstrapper API (see Initialize the Windows App SDK Framework package dynamically) to dynamically take a dependency on the Windows App SDK framework package. This enables you to use the Windows App SDK APIs in your app.
Open the Program.cs code file, and replace the default code with the following code to call the Bootstrap.Initialize method to initialize the bootstrapper. This code defines what version of the Windows App SDK the app is dependent upon when initializing the bootstrapper.
Important
You'll need to edit the code below to suit your specific configuration. See the descriptions of the parameters of the Bootstrap.Initialize method so that you can specify one of the versions of the Windows App SDK that you have installed.
using System; using Microsoft.Windows.ApplicationModel.DynamicDependency; namespace DynamicDependenciesTest { class Program { static void Main(string[] args) { Bootstrap.Initialize(0x00010005); Console.WriteLine("Hello, World!"); // Release the DDLM and clean up. Bootstrap.Shutdown(); } } }Note
The hexadecimal value passed to
Bootstrap.Initializeencodes the major and minor version of the Windows App SDK runtime your app targets.0x00010005represents version 1.5. Update this value to match the Windows App SDK version your project references (for example,0x00010006for version 1.6).At its root, the bootstrapper API is a native C/C++ API that enables you to use the Windows App SDK APIs in your app. But in a .NET app that uses the Windows App SDK 1.0 or later, you can use the .NET wrapper for the bootstrapper API. That wrapper provides an easier way of calling the bootstrapper API in a .NET app than calling the native C/C++ functions directly. The previous code example calls the static Initialize and Shutdown methods of the Bootstrap class in the .NET wrapper for the bootstrapper API.
To demonstrate that the Windows App SDK runtime components were loaded properly, add some code that uses the ResourceManager class in the Windows App SDK to load a string resource.
Add a new Resources File (.resw) to your project (leave the default name).
With the resources file open in the editor, create a new string resource with the following properties.
- Name: Message
- Value: Hello, resources!
Save the resources file.
Open the Program.cs code file, and replace the
Console.WriteLine("Hello, World!");line with the following code.
// Create a resource manager using the resource index generated during build. var manager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager("DynamicDependenciesTest.pri"); // Look up a string in the .resw file using its name. Console.WriteLine(manager.MainResourceMap.GetValue("Resources/Message").ValueAsString);- Click Start Without Debugging (or Start Debugging) to build and run your app. You should see the string
Hello, resources!successfully displayed.
If your project is WPF
For a Windows Presentation Foundation (WPF) app, see Use the Windows App SDK in an existing project.
Related topics
Windows developer

