Tutorial: Use the bootstrapper API in an app packaged with external location or unpackaged that uses the Windows App SDK

Follow these instructions to configure a C# WinUI 3 project that's either packaged with external location, or unpackaged.

1. 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.

2. Next, configure your project.

   1. In Solution Explorer, right-click your project and choose Edit Project File.
   2. 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>net6.0-windows10.0.19041.0</TargetFramework>
   

   1. Save and close the project file.

3. Change the platform for your solution to x64. The default value in a .NET project is AnyCPU, but WinUI 3 doesn't support that platform.

   1. Select Build > Configuration Manager.
   2. Select the drop-down under Active solution platform and click New to open the New Solution Platform dialog box.
   3. In the drop-down under Type or select the new platform, select x64.
   4. Click OK to close the New Solution Platform dialog box.
   5. In Configuration Manager, click Close.

4. Install the Windows App SDK NuGet package in your project.

   1. In Solution Explorer, right-click the Dependencies node and choose Manage Nuget Packages.
   2. In the NuGet Package Manager window, select the Browse tab, and install the Microsoft.WindowsAppSDK package.

5. You're now ready to use the bootstrapper API (see Use the Windows App SDK runtime for apps packaged with external location or unpackaged) 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(0x00010002);
               Console.WriteLine("Hello, World!");
   
               // Release the DDLM and clean up.
               Bootstrap.Shutdown();
           }
       }
   }
   

   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.

6. 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.

   1. Add a new Resources File (.resw) to your project (leave the default name).

   2. With the resources file open in the editor, create a new string resource with the following properties.

      • Name: Message
      • Value: Hello, resources!

   3. Save the resources file.

   4. 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);
   

   1. Click Start Without Debugging (or Start Debugging) to build and run your app. You should see the string Hello, resources! successfully displayed.

Follow these instructions to configure a C++ WinUI 3 project that's either packaged with external location, or unpackaged.

1. 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.

2. Next, install the Windows App SDK NuGet package in your project.

   1. In Solution Explorer, right-click the References node and choose Manage Nuget Packages.
   2. In the NuGet Package Manager window, select the Browse tab, and search for Microsoft.WindowsAppSDK.

3. You're now ready to use the bootstrapper API (see Use the Windows App SDK runtime for apps packaged with external location or unpackaged) to initialize the Windows App SDK runtime in your app. This enables you to use the Windows App SDK APIs in the app.

   1. Add the following include files to the top of your DynamicDependenciesTest.cpp file. The mddbootstrap.h header is available via the Windows App SDK NuGet package.

   #include <windows.h>
   #include <MddBootstrap.h>
   

   1. Next, add this code at the beginning of your main method to call the MddBootstrapInitialize function to initialize the bootstrapper, and handle any errors. 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 MddBootstrapInitialize function so that you can specify one of the versions of the Windows App SDK that you have installed.

   const UINT32 majorMinorVersion{ 0x00010002 }; 
   PCWSTR versionTag{ L"" }; 
   const PACKAGE_VERSION minVersion{};
   
   const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
   // Check the return code for errors. If there is an error, display the result.
   if (FAILED(hr)) 
   { 
       wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
           hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
       return hr; 
   } 
   

   1. Finally, add this code to display the string Hello, World! and call the MddBootstrapShutdown function to uninitialize the bootstrapper.

   std::cout << "Hello, World!\n"; 
   
   // Release the DDLM and clean up.
   MddBootstrapShutdown(); 
   

   1. Your final code should look like this.

   #include <iostream> 
   #include <windows.h> 
   #include <MddBootstrap.h>
   
   int main() 
   { 
       // Take a dependency on Windows App SDK Stable.
       const UINT32 majorMinorVersion{ 0x00010002 }; 
       PCWSTR versionTag{ L"" }; 
       const PACKAGE_VERSION minVersion{};
   
       const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
       // Check the return code. If there is a failure, display the result.
       if (FAILED(hr)) 
       { 
           wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
               hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
           return hr; 
       } 
   
       std::cout << "Hello, World!\n"; 
   
       // Release the DDLM and clean up.
       MddBootstrapShutdown(); 
   } 
   

4. Click Start Without Debugging (or Start Debugging) to build and run your app.