Rich information on Bootstrap initalization failure

build/NuSpecs/Microsoft.WindowsAppSDK.Bootstrap.CS.targets

@@ -1,7 +1,23 @@
-<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> 
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
 
-    <Target Name="GenerateBootstrapCS" 
-            BeforeTargets="BeforeCompile">
+    <PropertyGroup Condition="'$(WindowsAppSDKBootstrapInitialize)'==''">
+        <WindowsAppSDKBootstrapInitialize>true</WindowsAppSDKBootstrapInitialize>
+    </PropertyGroup>
+
+    <PropertyGroup Condition="'$(WindowsAppSDKBootstrapInitialize)'=='true'">
+        <DefineConstants
+        <DefineConstants Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_Default)'=='true'">$(DefineConstants);MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_DEFAULT</DefineConstants>
+        <DefineConstants Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_None)'=='true'">$(DefineConstants);MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_NONE</DefineConstants>
+        <DefineConstants Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak)'=='true'">$(DefineConstants);MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONERROR_DEBUGBREAK</DefineConstants>
+        <DefineConstants Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached)'=='true'">$(DefineConstants);MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONERROR_DEBUGBREAK_IFDEBUGGERATTACHED</DefineConstants>
+        <DefineConstants Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast)'=='true'">$(DefineConstants);MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONERROR_FAILFAST</DefineConstants>
+        <DefineConstants Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI)'=='true'">$(DefineConstants);MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONNOMATCH_SHOWUI</DefineConstants>
+        <DefineConstants Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp)'=='true'">$(DefineConstants);MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONPACKAGEIDENTITY_NOOP</DefineConstants>
+    </PropertyGroup>
+
+    <Target Name="GenerateBootstrapCS"
+            BeforeTargets="BeforeCompile"
+            Condition="'$(WindowsAppSDKBootstrapInitialize)'=='true'">
         <ItemGroup>
             <Compile Include="$(MSBuildThisFileDirectory)..\include\MddBootstrapAutoInitializer.cs" />
             <Compile Include="$(MSBuildThisFileDirectory)..\include\WindowsAppSDK-VersionInfo.cs" />

build/NuSpecs/WindowsAppSDK-Nuget-Native.Bootstrap.targets

@@ -1,11 +1,23 @@
-<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> 
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
 
-    <Target Name="GenerateBootstrapCpp" 
-            BeforeTargets="ClCompile">
+    <PropertyGroup Condition="'$(WindowsAppSDKBootstrapInitialize)'==''">
+        <WindowsAppSDKBootstrapInitialize>true</WindowsAppSDKBootstrapInitialize>
+    </PropertyGroup>
+
+    <Target Name="GenerateBootstrapCpp"
+            BeforeTargets="ClCompile"
+            Condition="'$(WindowsAppSDKBootstrapInitialize)'=='true'">
         <ItemGroup>
-			<ClCompile Include="$(MSBuildThisFileDirectory)..\..\include\MddBootstrapAutoInitializer.cpp">
-				<PrecompiledHeader>NotUsing</PrecompiledHeader>
-			</ClCompile>
+            <ClCompile Include="$(MSBuildThisFileDirectory)..\..\include\MddBootstrapAutoInitializer.cpp">
+                <PrecompiledHeader>NotUsing</PrecompiledHeader>
+                <PreprocessorDefinitions Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_Default)'=='true'">MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_DEFAULT;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+                <PreprocessorDefinitions Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_None)'=='true'">MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_NONE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+                <PreprocessorDefinitions Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak)'=='true'">MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONERROR_DEBUGBREAK;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+                <PreprocessorDefinitions Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached)'=='true'">MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONERROR_DEBUGBREAK_IFDEBUGGERATTACHED;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+                <PreprocessorDefinitions Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast)'=='true'">MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONERROR_FAILFAST;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+                <PreprocessorDefinitions Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI)'=='true'">MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONNOMATCH_SHOWUI;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+                <PreprocessorDefinitions Condition="'$(WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp)'=='true'">MICROSOFT_WINDOWSAPPSDK_BOOTSTRAP_AUTO_INITIALIZE_OPTIONS_ONPACKAGEIDENTITY_NOOP;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+            </ClCompile>
         </ItemGroup>
     </Target>
 

dev/Bootstrap/CS/Microsoft.WindowsAppRuntime.Bootstrap.Net/Bootstrap.cs

@@ -66,11 +66,11 @@ public override string ToString()
 
     internal static class NativeMethods
     {
-        [DllImport("Microsoft.WindowsAppRuntime.Bootstrap.dll", EntryPoint = "MddBootstrapInitialize", CharSet = CharSet.Unicode, ExactSpelling = true, PreserveSig = false)]
-        internal static extern void MddBootstrapInitialize_Throw(uint majorMinorVersion, string versionTag, PackageVersion packageVersion);
+        [DllImport("Microsoft.WindowsAppRuntime.Bootstrap.dll", EntryPoint = "MddBootstrapInitialize2", CharSet = CharSet.Unicode, ExactSpelling = true, PreserveSig = false)]
+        internal static extern void MddBootstrapInitialize2_Throw(uint majorMinorVersion, string versionTag, PackageVersion packageVersion, Bootstrap.InitializeOptions options);
 
         [DllImport("Microsoft.WindowsAppRuntime.Bootstrap.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
-        internal static extern int MddBootstrapInitialize(uint majorMinorVersion, string versionTag, PackageVersion packageVersion);
+        internal static extern int MddBootstrapInitialize2(uint majorMinorVersion, string versionTag, PackageVersion packageVersion, Bootstrap.InitializeOptions options);
 
         [DllImport("Microsoft.WindowsAppRuntime.Bootstrap.dll", ExactSpelling = true)]
         internal static extern void MddBootstrapShutdown();
@@ -79,17 +79,40 @@ internal static class NativeMethods
     // The Windows App SDK bootstrap initialization API.
     public class Bootstrap
     {
+        /// Options for Bootstrap initialization APIs.
+        public enum InitializeOptions : int
+        {
+            /// Default behavior
+            None = 0,
+
+            /// If not successful call DebugBreak()
+            OnError_DebugBreak = 0x0001,
+
+            /// If not successful call DebugBreak() if a debugger is attached to the process
+            OnError_DebugBreak_IfDebuggerAttached = 0x0002,
+
+            /// If not successful perform a fail-fast
+            OnError_FailFast = 0x0004,
+
+            /// If a compatible Windows App Runtime framework package is not found show UI
+            OnNoMatch_ShowUI = 0x0008,
+
+            /// Do nothing (do not error) if the process has package identity
+            OnPackageIdentity_NOOP = 0x0010,
+        }
+
         /// Initialize the calling process to use Windows App SDK's framework package.
         ///
         /// Find a Windows App SDK framework package meeting the criteria and make it available
         /// for use by the current process. If multiple packages meet the criteria the best
         /// candidate is selected.
         ///
-        /// This is equivalent to `Initialize(majorMinorVersion, null, new PackageVersion())`.
+        /// This is equivalent to `Initialize(majorMinorVersion, null, new PackageVersion(), InitializeOptions.None)`.
         ///
         /// @param majorMinorVersion major and minor version of Windows App SDK's framework package, encoded as `0xMMMMNNNN` where M=Major, N=Minor (e.g. 1.2 == 0x00010002).
         /// @see Initialize(uint, string)
         /// @see Initialize(uint, string, PackageVersion)
+        /// @see Initialize(uint, string, PackageVersion, InitializeOptions)
         /// @see Shutdown()
         public static void Initialize(uint majorMinorVersion)
         {
@@ -102,12 +125,13 @@ public static void Initialize(uint majorMinorVersion)
         /// for use by the current process. If multiple packages meet the criteria the best
         /// candidate is selected.
         ///
-        /// This is equivalent to `Initialize(majorMinorVersion, versionTag, new PackageVersion())`.
+        /// This is equivalent to `Initialize(majorMinorVersion, versionTag, new PackageVersion(), InitializeOptions.None)`.
         ///
         /// @param majorMinorVersion major and minor version of Windows App SDK's framework package, encoded as `0xMMMMNNNN` where M=Major, N=Minor (e.g. 1.2 == 0x00010002).
         /// @param versionTag version tag (if any), e.g. "preview1".
         /// @see Initialize(uint)
         /// @see Initialize(uint, string, PackageVersion)
+        /// @see Initialize(uint, string, PackageVersion, InitializeOptions)
         /// @see Shutdown()
         public static void Initialize(uint majorMinorVersion, string versionTag)
         {
@@ -120,15 +144,37 @@ public static void Initialize(uint majorMinorVersion, string versionTag)
         /// for use by the current process. If multiple packages meet the criteria the best
         /// candidate is selected.
         ///
+        /// This is equivalent to `Initialize(majorMinorVersion, versionTag, minVersion, InitializeOptions.None)`.
+        ///
         /// @param majorMinorVersion major and minor version of Windows App SDK's framework package, encoded as `0xMMMMNNNN` where M=Major, N=Minor (e.g. 1.2 == 0x00010002).
         /// @param versionTag version tag (if any), e.g. "preview1".
-        /// @param minVersion the minimum version to use
+        /// @param minVersion the minimum version to use.
         /// @see Initialize(uint)
         /// @see Initialize(uint, string)
+        /// @see Initialize(uint, string, PackageVersion, InitializeOptions)
         /// @see Shutdown()
         public static void Initialize(uint majorMinorVersion, string versionTag, PackageVersion minVersion)
         {
-            NativeMethods.MddBootstrapInitialize_Throw(majorMinorVersion, versionTag, minVersion);
+            NativeMethods.MddBootstrapInitialize2_Throw(majorMinorVersion, versionTag, minVersion, InitializeOptions.None);
+        }
+
+        /// Initialize the calling process to use Windows App SDK's framework package.
+        ///
+        /// Find a Windows App SDK framework package meeting the criteria and make it available
+        /// for use by the current process. If multiple packages meet the criteria the best
+        /// candidate is selected.
+        ///
+        /// @param majorMinorVersion major and minor version of Windows App SDK's framework package, encoded as `0xMMMMNNNN` where M=Major, N=Minor (e.g. 1.2 == 0x00010002).
+        /// @param versionTag version tag (if any), e.g. "preview1".
+        /// @param minVersion the minimum version to use.
+        /// @param options optional behavior.
+        /// @see Initialize(uint)
+        /// @see Initialize(uint, string)
+        /// @see Initialize(uint, string, PackageVersion)
+        /// @see Shutdown()
+        public static void Initialize(uint majorMinorVersion, string versionTag, PackageVersion minVersion, InitializeOptions options)
+        {
+            NativeMethods.MddBootstrapInitialize2_Throw(majorMinorVersion, versionTag, minVersion, options);
         }
 
         /// Initialize the calling process to use Windows App SDK's framework package.
@@ -138,12 +184,12 @@ public static void Initialize(uint majorMinorVersion, string versionTag, Package
         /// for use by the current process. If multiple packages meet the criteria the best
         /// candidate is selected.
         ///
-        /// This is equivalent to `TryInitialize(majorMinorVersion, null, new PackageVersion(), hresult)`.
+        /// This is equivalent to `TryInitialize(majorMinorVersion, null, new PackageVersion(), InitializeOptions.None, hresult)`.
         ///
         /// @param majorMinorVersion major and minor version of Windows App SDK's framework package, encoded as `0xMMMMNNNN` where M=Major, N=Minor (e.g. 1.2 == 0x00010002).
         /// @retval true if successful, otherwise false is returned.
         /// @see TryInitialize(uint, string, out int)
-        /// @see TryInitialize(uint, string, PackageVersion, out int)
+        /// @see TryInitialize(uint, string, PackageVersion, InitializeOptions, out int)
         /// @see Shutdown()
         public static bool TryInitialize(uint majorMinorVersion, out int hresult)
         {
@@ -157,13 +203,14 @@ public static bool TryInitialize(uint majorMinorVersion, out int hresult)
         /// for use by the current process. If multiple packages meet the criteria the best
         /// candidate is selected.
         ///
-        /// This is equivalent to `TryInitialize(majorMinorVersion, versionTag, new PackageVersion(), hresult)`.
+        /// This is equivalent to `TryInitialize(majorMinorVersion, versionTag, new PackageVersion(), InitializeOptions.None, hresult)`.
         ///
         /// @param majorMinorVersion major and minor version of Windows App SDK's framework package, encoded as `0xMMMMNNNN` where M=Major, N=Minor (e.g. 1.2 == 0x00010002).
         /// @param versionTag version tag (if any), e.g. "preview1".
         /// @retval true if successful, otherwise false is returned.
         /// @see TryInitialize(uint, out int)
         /// @see TryInitialize(uint, string, PackageVersion, out int)
+        /// @see TryInitialize(uint, string, PackageVersion, InitializeOptions, out int)
         /// @see Shutdown()
         public static bool TryInitialize(uint majorMinorVersion, string versionTag, out int hresult)
         {
@@ -178,17 +225,43 @@ public static bool TryInitialize(uint majorMinorVersion, string versionTag, out
         /// for use by the current process. If multiple packages meet the criteria the best
         /// candidate is selected.
         ///
+        /// This is equivalent to `TryInitialize(majorMinorVersion, versionTag, minVersion, InitializeOptions.None, hresult)`.
+        ///
         /// @param majorMinorVersion major and minor version of Windows App SDK's framework package, encoded as `0xMMMMNNNN` where M=Major, N=Minor (e.g. 1.2 == 0x00010002).
         /// @param versionTag version tag (if any), e.g. "preview1".
         /// @param minVersion the minimum version to use.
+        /// @param options optional behavior.
         /// @param hresult the error code if an error occurred.
         /// @retval true if successful, otherwise false is returned.
         /// @see TryInitialize(uint, out int)
         /// @see TryInitialize(uint, string, out int)
+        /// @see TryInitialize(uint, string, PackageVersion, out int)
         /// @see Shutdown()
         public static bool TryInitialize(uint majorMinorVersion, string versionTag, PackageVersion minVersion, out int hresult)
         {
-            hresult = NativeMethods.MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion);
+            return TryInitialize(majorMinorVersion, versionTag, minVersion, InitializeOptions.None, out hresult);
+        }
+
+        /// Initialize the calling process to use Windows App SDK's framework package.
+        /// Failure returns false with the failure HRESULT in the hresult parameter.
+        ///
+        /// Find a Windows App SDK framework package meeting the criteria and make it available
+        /// for use by the current process. If multiple packages meet the criteria the best
+        /// candidate is selected.
+        ///
+        /// @param majorMinorVersion major and minor version of Windows App SDK's framework package, encoded as `0xMMMMNNNN` where M=Major, N=Minor (e.g. 1.2 == 0x00010002).
+        /// @param versionTag version tag (if any), e.g. "preview1".
+        /// @param minVersion the minimum version to use.
+        /// @param options optional behavior.
+        /// @param hresult the error code if an error occurred.
+        /// @retval true if successful, otherwise false is returned.
+        /// @see TryInitialize(uint, out int)
+        /// @see TryInitialize(uint, string, out int)
+        /// @see TryInitialize(uint, string, PackageVersion, out int)
+        /// @see Shutdown()
+        public static bool TryInitialize(uint majorMinorVersion, string versionTag, PackageVersion minVersion, InitializeOptions options, out int hresult)
+        {
+            hresult = NativeMethods.MddBootstrapInitialize2(majorMinorVersion, versionTag, minVersion, options);
             return hresult >= 0;
         }
 
@@ -199,9 +272,11 @@ public static bool TryInitialize(uint majorMinorVersion, string versionTag, Pack
         /// @see Initialize(uint)
         /// @see Initialize(uint, string)
         /// @see Initialize(uint, string, PackageVersion)
+        /// @see Initialize(uint, string, PackageVersion, InitializeOptions options)
         /// @see TryInitialize(uint, out int)
         /// @see TryInitialize(uint, string, out int)
         /// @see TryInitialize(uint, string, PackageVersion, out int)
+        /// @see TryInitialize(uint, string, PackageVersion, InitializeOptions options, out int)
         public static void Shutdown()
         {
             NativeMethods.MddBootstrapShutdown();