VS Code and the .NET MAUI Extension - Path to Success

So you want to use the new .NET MAUI extension for VS Code? Great call! Or maybe you have been using it for a while and suddenly hit issues! Well you're not alone!

I recently purchased a new Macbook Air M2 and was determined to forget about VS for Mac (since it is being retired soon) and just try and get started with the new VS Code Extension. At time of writing it's still in preview so it's not as feature complete as the team want, but its still amazing and worth trying out.

But I discovered that through user error (obviously my own lol), its possible at the moment to get tangled up and hit some issues. Thankfully, the amazing Maddy Montaquila was at Swetugg conference with me in Sweden and was able to solve my issues one step at a time. So this is an FAQ/troubleshooting guide to maybe help you on your path to MAUI success.

TLDR: It's probably Xcode's fault! 😂 Check for Xcode updates and check that you have the most recent iOS Simulators downloaded. Check for this in Settings -> Platforms.

This might seem really obvious but make sure the .NET MAUI extension is installed. I had uninstalled it while trying to resolve some other issues and not realised I hadn't reinstalled so I went to run an application and couldn't see the options I was expecting. You can tell that the extension is not installed because you won't have the curly brackets in the bottom right on the toolbar. Or it will see a .XAML file as XML. Both of these are signs that the extension is missing.

This error message came up a few times and it threw me at first. I tried adding what I thought it wanted in the csproj file but no luck. Maddy to the rescue! Just add the following to your csproj file:

<SelfContained>false</SelfContained>

When I was Googling the previous error myself about RunTimeIdentifier and self contained, one of the results I read suggested adding a global.json file and specifying the version of .NET. I even tried setting it to .NET 7 just to get something working since its a change in .NET 8. However, when making the above change in csproj and making sure it worked, it was still giving me strange errors about versions.

So that is another thing to note, if you have a global.json file in the root of your project, make sure that the versions of .NET are the same between that and your csproj.

This is one of those annoying ones caused by none other than Apple! It is related to their focus on security which isn't necessarily a bad thing but causes MAUI developers (and the PM team) a regular headache.

They try to protect your Documents folder so if your solution is in the documents folder, it can fail to run on MacOS. Just move the folder to your home folder, or a folder such as Dev inside the home folder.

This one caught me out because I'm a big believer in the P.A.R.A method from Tiago Forte (productivity and organisational thing) so rather than have a Dev folder, I store my app folders in the right folder related to what the app is related to. For example, my Blazor application for my website rewrite is inside a folder called 'Luce Carter Website' inside a folder called 'Projects' in my Documents folder. This works for me for nearly all things, except MAUI it seems.

By the time you read this, this might be solved. But there is a weird issue sometimes where the CLI path gets emptied from Xcode settings.

Open Xcode -> Settings -> Locations and make sure the Command Line Tools drop down isn't empty.

I touched on this at the beginning but when all else fails, a good idea, besides the usual deleting of the bin and obj folders, and restarting the text editor or IDE, is to check for updates of Xcode.

A lot of issues come up in MAUI development when Xcode is out of date. So one of the first things to do is check for Xcode updates. I had totally forgotten about that, after being a Windows MAUI developer for a long time. But when I was having issues, hero Maddy flew in and suggested I check for updates and would you believe it, there was an update! We all dread Xcode updates because they are such large files and take a while. But its just something you have to deal with for a smooth MAUI experience.

Another good thing to check is if the xcode-select CLI tools are installed. From a terminal, run xcode-select --install.

If the tools are already installed, you will see a message that lets you know.

It is also a good idea to check for any updates of the extension itself. If there is one available, you will see it in the Extensions area within VS Code.

Simulator isn't starting or Mac Catalyst won't run

Another issue I stumbled across while updating Xcode, is that things needing any kind of iOS or Xcode tooling wouldn't work.

It turns out that while updating, all files and apps (such as the Simulator) related to Xcode get locked. It won't tell you this in any error messages in VS Code, but you will notice things like the Simulator never starting as requested.

Sadly the only solution to this is patience.

I've just updated Xcode yet iOS Simulator versions aren't showing in the dropdown list

When you update Xcode, it doesn't always download the latest iOS simulators automatically. VS Code is looking for simulators with the iOS version that goes with the latest version of Xcode so if you don't have these downloaded, even when iOS is selected in VS Code, you won't see the simulators listed.

Open Xcode -> Settings -> Platforms tab and click 'Get' next to the latest simulators if you need to.

Sometimes, if you happen to try and run a MAUI app in VS Code while Xcode is updating, it will change the debug target on you and you may not notice, usually to MacCatalyst (Build Only). Once Xcode is installed, next time you go to run the app in VS Code, it is a good idea to check the debug target in the extension first.

Just click the curly braces in the bottom right of the VS Code window and check the debug target.

Bonus tip: you can click the pin icon to make sure you can always see the debug target to change it without having to click the curly braces first

So there we have it, a list of potential things to try if you have any issues on your path to MAUI success.

Of course some are less troubleshooting points and more things to be aware of. But overall, keep Xcode up to date, don't use the Documents folder if you intend to target MacOS, make sure you have the latest iOS simulators installed via Xcode and check your debug target in VS Code.

If you have any other issues and solutions you want to share, be sure to X me @LuceCarter1 with your favourite tips or tricks or just solutions and I will add them to this very blog with public credit :D.

Thanks again to Maddy who inspired this blog post and got me unstuck on my latest MAUI project! <3