Add a doc to help troubleshoot package mixups

Now that source-built .NET Core is becoming more widespread, people are
hitting issues when some packages on their machines come from the
Microsoft repos and others from the distro archive. They don't mix well:
they have different dotnet roots, /usr/share/dotnet vs.
/usr/lib64/dotnet.

Document some way to identify this problem and some solutions based on
what the users want to do.

Fixes: dotnet#18347

docs/core/install/linux-centos.md

@@ -71,6 +71,10 @@ This section provides information on common errors you may get while using the p
 
 [!INCLUDE [package-manager-failed-to-fetch-rpm](includes/package-manager-failed-to-fetch-rpm.md)]
 
+### Errors about missing `fxr`, `libhostfxr.so` or `FrameworkList.xml`
+
+See how to [Troubleshoot Package Mixups](linux-package-mixup.md)
+
 ## Dependencies
 
 [!INCLUDE [linux-rpm-install-dependencies](includes/linux-rpm-install-dependencies.md)]

docs/core/install/linux-fedora.md

@@ -102,6 +102,10 @@ For more information on installing .NET without a package manager, see one of th
 
 [!INCLUDE [package-manager-failed-to-fetch-rpm](includes/package-manager-failed-to-fetch-rpm.md)]
 
+### Errors about missing `fxr`, `libhostfxr.so` or `FrameworkList.xml`
+
+See how to [Troubleshoot Package Mixups](linux-package-mixup.md)
+
 ## Next steps
 
 - [How to enable TAB completion for the .NET CLI](../tools/enable-tab-autocomplete.md)

docs/core/install/linux-package-mixup.md

@@ -0,0 +1,102 @@
+---
+title: Troubleshoot Package Mixup
+description: Learn about how to troubleshoot strange .NET packae errors on Linux.
+author: omajid
+ms.date: 05/12/2021
+---
+
+# Troubleshoot `fxr`, `libhostfxr.so` or `FrameworkList.xml` errors
+
+Users trying to use .NET and .NET Core may run into .NET commands (`dotnet new`, `dotnet build`, `dotnet run`) failing. The exact error messages can vary. Some example error messages:
+
+- https://github.com/dotnet/sdk/issues/12075
+  https://github.com/dotnet/sdk/issues/15785
+  https://github.com/dotnet/sdk/issues/15863
+  https://github.com/dotnet/sdk/issues/17411
+
+  System.IO.FileNotFoundException: Could not find file
+  '/usr/share/dotnet/packs/Microsoft.NETCore.App.Ref/5.0.0/data/FrameworkList.xml'.
+
+- https://github.com/dotnet/sdk/issues/17570
+
+  A fatal error occurred. The required library libhostfxr.so could not be found.
+
+- https://github.com/dotnet/core/issues/5746
+  https://github.com/dotnet/sdk/issues/15476
+
+  A fatal error occurred. The folder [/usr/share/dotnet/host/fxr] does not exist
+
+- https://github.com/dotnet/installer/issues/9254
+  https://stackoverflow.com/questions/65422998/
+
+  A fatal error occurred, the folder [/usr/share/dotnet/host/fxr] does not contain any version-numbered child folders
+
+And some symptoms without clear error messages:
+
+- https://github.com/dotnet/core/issues/4605
+  https://github.com/dotnet/core/issues/4655
+  https://github.com/dotnet/runtime/issues/49375
+
+  SDK is installed, but `dotnet` complains it isn't.
+
+Another common symptom of this problem is that you have both `/usr/lib64/dotnet` and `/usr/share/dotnet` on your machine.
+
+## What's going on?
+
+This generally happens when two Linux package repositories provide .NET packages. Often .NET packages are provided by the Linux distribution (eg, Arch, CentOS, Fedora, RHEL), in addition to Microsoft.
+
+Mixing .NET packages from two different sources will most likely lead to issues since they packages may place things at different paths, and may be compiled differently.
+
+## Some fixes
+
+The fix is to use .NET from one package repository only. Which repository to pick and how to do it varies by use-case and the Linux distribution.
+
+The first fix is probably the simplest (and best in the very long term) but there are some known issues that may lead to better outcomes for the user right now if they pick another option.
+
+,*Use case 1*: I only want to install/use .NET. I dont want to use any other packages - such as `mdatp`, `powershell` and `mssql` - from the Microsoft repository.
+
+In this case, remove the Microsoft repository, the .NET packages and then re-install the .NET packages from the Linux distribution repository.
+
+For Fedora, CentOS >= 8, and RHEL >=8:
+
+```bash
+$ sudo dnf remove package-microsoft-prod
+$ sudo dnf remove 'dotnet*' 'aspnet*' 'netstandard*'
+
+$ sudo dnf install dotnet-sdk-5.0
+```
+
+,*Use case 2*: I want to install and use .NET but also need other packages from Microsoft's repository, such as `mdatp`, `powershell` or `mssql`.
+
+In this case, keep the Microsoft repository, but configure it so that it doesn't provide any the .NET packages, remove the already-installed .NET packages and then re-install the .NET packages from the Linux distribution repository.
+
+For Fedora, CentOS >= 8, and RHEL >=8:
+
+```bash
+$ echo 'excludepkgs=dotnet*,aspnet*,netstandard*' | sudo tee -a /etc/yum.repos.d/microsoft-prod.repo
+$ sudo dnf remove 'dotnet*' 'aspnet*' 'netstandard*'
+
+$ sudo dnf install dotnet-sdk-5.0
+```
+
+,*Use case 3*: I need a recent version of .NET that's not available if I go with option 1 or 2.
+
+In this case, keep the Microsoft repository, and configure it so .NET packages from the Microsoft repository are considered a higher priority. Then remove the already-installed .NET packages and then re-install the .NET packages from the Microsoft repository.
+
+For Fedora, CentOS >= 8, and RHEL >=8:
+
+```bash
+$ echo 'priority=50' | sudo tee -a /etc/yum.repos.d/microsoft-prod.repo
+$ sudo dnf remove 'dotnet*' 'aspnet*' 'netstandard*'
+
+$ sudo dnf install dotnet-sdk-5.0
+```
+
+,*Use case 4* The version of .NET from the Linux distribution has bugs that are showstoppers for me and those bugs are fixed in the Microsoft packages.
+
+Follow the same steps as Use case 3.
+
+## Next steps
+
+- [Tutorial: Create a new app with Visual Studio Code](../tutorials/with-visual-studio-code.md).
+- [Tutorial: Containerize a .NET app](../docker/build-container.md).

docs/core/install/linux-rhel.md

@@ -139,6 +139,14 @@ As an alternative to the ASP.NET Core Runtime, you can install the .NET Core Run
 
 Consult the [Red Hat documentation for .NET](https://access.redhat.com/documentation/net/5.0/) on the steps required to install other releases of .NET.
 
+## Troubleshoot the package manager
+
+This section provides information on common errors you may get while using the package manager to install .NET or .NET Core.
+
+### Errors about missing `fxr`, `libhostfxr.so` or `FrameworkList.xml`
+
+See how to [Troubleshoot Package Mixups](linux-package-mixup.md)
+
 ## Next steps
 
 - [How to enable TAB completion for the .NET CLI](../tools/enable-tab-autocomplete.md)