[Unpackaged] - Improve error when bootstrapper cannot find default WindowsAppRuntime framework

[AdamBraden]

Describe the bug

Using <WindowsPackageType>None<WindowsPackageType> feature in 1.0, auto-initializes the lookup for the WindowsAppRuntime framework package. However if the framework cannot be found, it results in a generic exception:

Exception thrown: 'System.Runtime.InteropServices.COMException' in Microsoft.WindowsAppRuntime.Bootstrap.Net.dll

Recommend a better exception or logging a debug output error message.

Steps to reproduce the bug

On a clean machine that does not have the Windows App SDK installed

1. Start a new C# Winforms app targeting .NET6
2. Add a packagereference to the windows app sdk, and add None</> to auto-intialize your app code to find the MSIX framework package, eg:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net5.0-windows10.0.19041.0</TargetFramework>
    <RuntimeIdentifiers>win10-x86;win10-x64</RuntimeIdentifiers>
    <UseWindowsForms>true</UseWindowsForms>
    <WindowsPackageType>None</WindowsPackageType>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.0.0-preview3" />
  </ItemGroup>

</Project>

3. F5 to run the app, note the bootstrapper initialization will not find the framework and fail with this error:
   'WinFormsApp5.exe' (CoreCLR: clrhost): Loaded 'D:\repos\WinFormsApp5\bin\Debug\net5.0-windows10.0.19041.0\Microsoft.WindowsAppRuntime.Bootstrap.Net.dll'. Symbol loading disabled by Include/Exclude setting.
   Exception thrown: 'System.DllNotFoundException' in Microsoft.WindowsAppRuntime.Bootstrap.Net.dll

Expected behavior

No exception

Screenshots

No response

NuGet package version

1.0.0

Packaging type

Unpackaged

Windows version

Windows 11 (22000), May 2021 Update (19043), October 2020 Update (19042), May 2020 Update (19041), November 2019 Update (18363), May 2019 Update (18362), October 2018 Update (17763)

IDE

Visual Studio 2022

Additional context

No response

[dotMorten]

This! Better errors that tells us what is wrong and what we need to do is essential for a good developer experience. For a good example of how hard it is to troubleshoot check out the 20min mark in this video which got even an expert stumped :-) https://youtu.be/kDj9XeKYYJk?t=1193

[riverar]

@zaryaf @DrusTheAxe

[stewienj]

The bootstrapper should also check for the C++ runtime DLLs being available. These missing DLLs were the cause of #1762 .

[DrusTheAxe]

The bootstrapper should also check for the C++ runtime DLLs being available. These missing DLLs were the cause of #1762 .

WinAppSDK 1.0 requires the CRT runtime. This is a documented prerequisite. @zaryaf got link?

WinAppSDK 1.1 is moving to the Hybrid CRT per https://task.ms/35544838. WinUI is the last remaining component to update. @Scottj1s has an update in progress for 1.1

[DrusTheAxe]

However if the framework cannot be found, it results in a generic exception:
Exception thrown: 'System.Runtime.InteropServices.COMException' in Microsoft.WindowsAppRuntime.Bootstrap.Net.dll
Recommend a better exception or logging a debug output error message.

Or both :-)

It's in my queue. Happy holidays

[smaillet]

@AdamBraden Thanks for reporting this as a really bad error/experience, I couldn't agree more - I've spent several hours trying to get a simple WinU 3 app to build and run unpackaged to no avail but a LOT of frustration.

So What's the solution/workaround to this? I have this error and have no idea what to do about it... (sadly even this bug report leaves out any form of a solution)

[Update] Finally figured it out, apparently just adding the VSIX package to VS isn't enough, we also need to run (with admin rights) an additional installer that's only provided as a ZIP file leaving users to guess which one is needed for their systems.)

All up I have to say this is an atrociously bad experience for what used to be standard table stakes. (Building a standalone unpackaged EXE) There needs to be a simple solution for this that doesn't involve all these steps, and preferably it includes a project template that takes care of all the setup so it "just works". The need to install some additional runtime, instead of using NuGet etc.. to include binaries should be eliminated - that just makes using this Windows APP SDK much harder. Especially for .NET developers used to the idea of XCOPY deploy/F5 Debug.

[riverar]

[Update] Finally figured it out, apparently just adding the VSIX package to VS isn't enough, we also need to run (with admin rights) an additional installer that's only provided as a ZIP file leaving users to guess which one is needed for their systems.)

Did you read the Windows App SDK deployment guide for unpackaged apps beforehand?

Perhaps whatever error is added should have an aka.ms pointing to these docs.

The need to install some additional runtime, instead of using NuGet etc.. to include binaries should be eliminated [...]

Good news, a self-contained option seems to be coming in 1.1. (I haven't seen the spec for it, so I have my doubts but that's the official word right now.)

[smaillet]

@riverar Yes, I did RTFM, thank you. The docs are a jumbled mess of steps that vaguely reference one another and worse reference two almost identically named things VSIX installer AND an MSIX installer (or a set of them packaged as a ZIP file) there is literally one letter difference between the acronyms for those two things so it is all VERY confusing. Additionally the expectation is that one would NOT Need any sort of MSIX installer involved. I have the VSIX applied and I added the NuGet Package - there is pretty much no precedent to expect one needs anything more. I'd call it a serious design flaw that we do need more to support unpackaged apps - XCOPY deployment is the standard of .NET. Packaging should have any impact or the inner loop development of apps before they are even ready for any sort of deployment to anyone but other development team members. One can't even run the code built without the added MSIX stuff installed - that's VERY surprising with any library from NuGet. Bottom line here is that WinUI 3 is NOT XCOPY deploy compatible and the docs need to make that crystal clear right up front and the error message(s) should provide more helpful details people can understand that.

[riverar]

@smaillet I think that's all fair feedback!

To summarize your comment:

• You found the docs confusing (adding @zaryaf)
• You found the packaging-project/single-project templates are confusing (adding @andrewleader for the rest)
• You suspect the lack of xcopy deployment is contributing to confusion given it's a default in the .NET (Core) ecosystem
• WAS/WinUI error messages suck

[DrusTheAxe]

You found the docs confusing

+@AdamBraden

[DrusTheAxe]

1.0 servicing update (1.0.1?) and 1.1 include improved logging