Skip to content

Commit

Permalink
Add uninstallation instructions for .NET MAUI workloads (#1340)
Browse files Browse the repository at this point in the history 
* Add uninstallation instructions.

* Edit.

* Edits.

* Fix link.

* Fix link.

* Edits.
  • Loading branch information
@davidbritch
davidbritch committed Mar 8, 2023
1 parent 69e2374 commit 5b64c10
Showing 1 changed file with 75 additions and 17 deletions.
92 changes: 75 additions & 17 deletions docs/troubleshooting.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,76 @@
---
title: "Troubleshoot known issues"
description: "Describes the known issues and troubleshooting you can do to resolve these issues for a .NET Multi-platform App UI (.NET MAUI) app."
ms.date: 11/18/2022
description: "Learn about .NET MAUI known issues and troubleshooting you can do to resolve these issues."
ms.date: 03/08/2023
---

# Troubleshooting known issues

This article describes some of the known issues with .NET MAUI, and how you can solve or work around them. The [.NET MAUI code repository](https://github.com/dotnet/maui/wiki/Known-Issues) also details some known issues.
This article describes some of the known issues with .NET Multi-platform App UI (.NET MAUI), and how you can solve or work around them. The [.NET MAUI repository](https://github.com/dotnet/maui/wiki/Known-Issues) also details some known issues.

## Can't locate the .NET MAUI workloads

There are two options for installing the .NET MAUI workloads:

1. Visual Studio on Windows can install *.msi* files for each workload pack.
1. `dotnet workload install` commands.

On Windows, if you run a `dotnet workload install` after installing .NET MAUI through the Visual Studio installer, Visual Studio can enter a state where it can't locate the .NET MAUI workloads. You'll then receive build errors telling you to install the .NET MAUI workloads, and it's possible to enter a state where the workloads can't be repaired or re-installed. For more information about this issue, see [The CLI and VS do not play nicely](https://github.com/dotnet/sdk/issues/22388).

### Windows

The solution to this issue on Windows is to uninstall the .NET MAUI workloads through the CLI, uninstall any .NET SDKs in Control Panel, and uninstall the .NET MAUI workloads in Visual Studio. This can be accomplished with the following process:

1. Run `dotnet workload uninstall maui` if you ever used the `dotnet workload install` commands.
1. Uninstall any standalone .NET SDK installers from Control Panel. These will have names similar to `Microsoft .NET SDK 6.0.300`.
1. In every instance of Visual Studio, uninstall the .NET Multi-platform App UI development, and .NET desktop development Visual Studio workloads.

Then, check if there are additional `.msi` files that need uninstalling by running the following command:

```cmd
reg query HKLM\SOFTWARE\Microsoft\Windows\currentversion\uninstall\ -s -f manifest
```

This `reg query` command will list .NET 6+ SDKS that are still installed on your machine, such as:

```
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\currentversion\uninstall\{EEC1BB5F-3391-43C2-810E-42D78ADF3140}
InstallSource REG_SZ C:\ProgramData\Microsoft\VisualStudio\Packages\Microsoft.MacCatalyst.Manifest-6.0.300,version=125.179.40883,chip=x64,productarch=neutral\
DisplayName REG_SZ Microsoft.NET.Sdk.MacCatalyst.Manifest-6.0.300
```

If you receive similar output, you should copy the GUID for each package and uninstall the package with the `msiexec` command:

```cmd
msiexec /x {EEC1BB5F-3391-43C2-810E-42D78ADF3140} /q IGNOREDEPENDENCIES=ALL
```

Then, you should keep executing the `reg query` command until it doesn't return any results. Once this happens, and all .NET 6+ SDKs are uninstalled, you should also consider deleting the following folders:

- `C:\Program Files\dotnet\sdk-manifests`
- `C:\Program Files\dotnet\metadata`
- `C:\Program Files\dotnet\packs`
- `C:\Program Files\dotnet\library-packs`
- `C:\Program Files\dotnet\template-packs`
- `C:\Program Files\dotnet\sdk\6.*` or `C:\Program Files\dotnet\sdk\7.*`
- `C:\Program Files\dotnet\host\fxr\6.*` or `C:\Program Files\dotnet\host\fxr\7.*`

After following this process, you should be able to re-install .NET MAUI either through Visual Studio, or by installing your chosen .NET SDK version and running the `dotnet workload install maui` command.

### Mac

Visual Studio for Mac's installer and updater uses `dotnet workload install` commands to install the .NET MAUI *.pkg* files.

Since *.pkg* files can't be uninstalled, the simplest approach to uninstalling the workloads on a Mac is to run the following commands to delete the specified folders:

```zsh
rm -r ~/.dotnet/
sudo rm -r /usr/local/share/dotnet/
```

After executing these commands, you should be able to re-install .NET MAUI either through Visual Studio for Mac, or by installing your chosen .NET SDK version and running `dotnet workload install maui` command.

<!-- Leaving here in case this situation occurs with .NET 8
## Templates are missing
If you've installed Visual Studio 2022 and the **.NET Multi-platform App UI development** workload, but the .NET MAUI templates are missing, you most likely have a conflict with a .NET 7 preview version. To see if .NET 7 is being resolved as your current version of .NET, perform the following steps:
Expand Down Expand Up @@ -67,8 +130,9 @@ Use a `global.json` config file in the folder where you'll create the project. T
```
01. Open the project in Visual Studio.
-->

## ERROR Platform version is not present.
## Platform version isn't present

Visual Studio may not be resolving the required workloads if you try to compile a project and receive an error similar to the following text:

Expand All @@ -84,16 +148,9 @@ Visual Studio may not be resolving the required workloads if you try to compile
::: moniker-end

This problem is generally caused by one of the following scenarios:

- You have a .NET 7 preview installed, which doesn't support .NET MAUI.

There are a few options to fix this issue, you can either upgrade to a .NET 7 release candidate or remove the .NET 7 preview. Review the steps in the [Templates are missing](#templates-are-missing) section.

- You have both an x86 and x64 SDK installed, and the x86 version is being used.

Visual Studio and .NET MAUI require the x64 .NET SDK. If your operating system has a system-wide `PATH` variable that is resolving the x86 SDK first, you'll need to fix that by either removing the x86 .NET SDK from the `PATH` variable, or promoting the x64 .NET SDK so that it resolves first. For more information on troubleshooting x86 vs x64 SDK resolution, see [Install .NET on Windows - Troubleshooting](/dotnet/core/install/windows#it-was-not-possible-to-find-any-installed-net-core-sdks).
This problem typically results from having an x86 and x64 SDK installed, and the x86 version is being used. Visual Studio and .NET MAUI require the x64 .NET SDK. If your operating system has a system-wide `PATH` variable that is resolving the x86 SDK first, you'll need to fix that by either removing the x86 .NET SDK from the `PATH` variable, or promoting the x64 .NET SDK so that it resolves first. For more information on troubleshooting x86 vs x64 SDK resolution, see [Install .NET on Windows - Troubleshooting](/dotnet/core/install/windows#it-was-not-possible-to-find-any-installed-net-core-sdks).

<!--
## The WINDOWS `#if` directive is broken
The `WINDOWS` definition doesn't resolve correctly in the latest release of .NET MAUI. To work around this issue, add the following entry to the `<PropertyGroup>` element of your project file.
Expand All @@ -103,8 +160,9 @@ The `WINDOWS` definition doesn't resolve correctly in the latest release of .NET
```
The definitions that identify a specific version of Windows will still be missing.
-->

## ERROR Type or namespace 'Default' does not exist
## Type or namespace 'Default' does not exist

When using the [`Contacts` API](platform-integration/communication/contacts.md), you may see the following error related to iOS and macOS:

Expand All @@ -123,13 +181,13 @@ using Communication = Microsoft.Maui.ApplicationModel.Communication;
var contact = await Communication.Contacts.Default.PickContactAsync();
```

## Xcode is not currently installed or could not be found
## Xcode isn't currently installed or couldn't be found

After installing the Xcode command line tools, using `xcode-select --install`, Visual Studio for Mac might show a "Xcode is not currently installed or could not be found" message when attempting to build .NET MAUI apps that target iOS or Mac Catalyst. In this scenario, check that you also have Xcode installed from the App Store. Then, launch Xcode and go to **Xcode > Preferences > Locations > Command Line Tools** and check if the drop-down is empty. If it is empty, select the drop-down and then select the location of the Xcode command line tools. Then close Xcode and restart Visual Studio for Mac.

## Could not find a valid Xcode app bundle
## Couldn't find a valid Xcode app bundle

If you receive the error "Could not find a valid Xcode app bundle at '/Library/Developer/CommandLineTools'", when attempting to build .NET MAUI apps that target iOS or Mac Catalyst, you should try the solution described in [Xcode is not currently installed or could not be found](#xcode-is-not-currently-installed-or-could-not-be-found). If you're still unable to access the **Xcode > Preferences > Locations > Command Line Tools** drop-down, run the following command:
If you receive the error "Could not find a valid Xcode app bundle at '/Library/Developer/CommandLineTools'", when attempting to build .NET MAUI apps that target iOS or Mac Catalyst, you should try the solution described in [Xcode isn't currently installed or couldn't be found](#xcode-isnt-currently-installed-or-couldnt-be-found). If you're still unable to access the **Xcode > Preferences > Locations > Command Line Tools** drop-down, run the following command:

```zsh
sudo xcode-select --reset
Expand Down

0 comments on commit 5b64c10

Please sign in to comment.