WinUI 3 exe Gotchas

For small to mid-sized companies, portable executables just make sense. The path to making an exe file instead of a MSIX file can be a frustrating one and the documentation is lacking. Here's steps I've had to do.

Run as an Unpackaged App

Make sure your program can run as an unpackaged program. Where you hit the "play" button, drop down to Unpackaged (MSIX experience is the packaged version).

• If your project does not debug at all without throwing errors, make the rest of the changes in the points below, go through a "Publish" and then try again once it publishes successfully. Don't know why, but i had to do this before the switch would build correctly.
• This may break your program so make sure you test your functionality from beginning to end. For example, my packaged version of an app i was making worked fine to use a File Picker and then use a CachedFileManager to write out to that file; however, CachedFileManagers aren't supported in non-packaged apps so when I switched, I suddenly got weird errors around the state of the CachedFileManager. Fortunately, there's a list of non-supported APIs (https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/desktop-to-uwp-supported-api). If you suddenly encounter a break, I'd start here. It turns out the CachedFileManager requires package identity (there are certain APIs that the OS must know what package is making the call to that API, this is done through package identity). I worked around by using a different approach to writing out a file and it worked fine after that (see https://learn.microsoft.com/en-us/windows/apps/get-started/intro-pack-dep-proc)

Add the Non-Packaged properties

<WindowsPackageType>None</WindowsPackageType>
<WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>

• Add these properties to your app settings file (csproj). How do you open this file? Double click the name of your project in the Solution Explorer (not the name of the solution). Add the above properties into the csproj file as seen above. These help indicate you want a non-packaged program. Running a WinUI program requires the WinUI runtime. If you want a framework dependent executable that uses the installed runtime, you should be able to leave the WindowsAppSDKSelfContained property off, but I could not get this to work. Good luck on your research if that is your path.

Adjust/Create a Publish Profile

You will need to create a publish profile.

• Select Build>Publish Selection from the top menu. It will open a dialogue to create a publish profile.
• In the end, my settings looked like this (notice the x64 config selections, and the deployment mode set to Self-contained). Finally select to show other settings and select "Produce single file". Save this.
• You can try now to "Publish" which will take a few minutes. If it publishes successfully, assuming you've already run it through debug mode in unpackaged mode, you should now check and make sure the executable works correctly (from beginning to end). If your debugger did not work correctly after switching to unpackaged, go try it again. If publishing fails or your executable crashes in weird places, review the additional properties below.

Review Project Properties

Review the properties for the project by right-clicking and selecting properties. Make sure your versioning looks correct. Also try to de-select Optimize Code and Publish Trimmed. These have fixed random crashes or compile issues for me, though they do make for a bigger executable.

The exe Works Fine in Debugger But Crashes in RunTime

I've had this happen before and mystically fixed it without code changes by toying with the trim options and optimization properties above and republishing each time to test. If the app appears not to launch at all, make sure you have the proper runtimes installed. You should have the appropriate .net version installed. If you are publishing as Framework dependent (and not self-contained) make sure you have the appropriate WinUI Runtime installed as well (I do not envy you as your path is dark and the outcome is uncertain). If your app launches, but then crashes at a later point, you can launch an instance of Visual Studio without code, and then use the Debug>attach to process to try and catch any unhandled exception that may be the missing clue to your woes.

THERE SEEMS TO BE AN ISSUE WITH VS! I wasted a couple of days on a program that threw no apparent error but wouldn't run. The executable WOULD run if "produce a single file" was unchecked and I ran it in from that setting. In this case, try deleting the bin and obj folders (you will have to unhide hidden files) and then re-publish. This was the fix for me...this time.