diff --git a/docs/core/install/includes/supported-versions.md b/docs/core/install/includes/supported-versions.md new file mode 100644 index 0000000000000..15eb1c56e5a93 --- /dev/null +++ b/docs/core/install/includes/supported-versions.md @@ -0,0 +1,15 @@ +--- +author: adegeo +ms.author: adegeo +ms.date: 05/22/2024 +ms.topic: include +--- + +Microsoft publishes .NET under two different support policies, Long Term Support (LTS) and Standard Term Support (STS). The quality of all releases is the same. The only difference is the length of support. LTS releases get free support and patches for three years. STS releases get free support and patches for 18 months. For more information, see [.NET Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). + +The versions of .NET that are currently supported by Microsoft are: + +- 8.0 (LTS)—Support ends **November 10, 2026**. +- 6.0 (LTS)—Support ends **November 12, 2024**. + +Other entities that build and release .NET might introduce different support policies. Be sure to check with them to understand how .NET is supported. diff --git a/docs/core/install/linux-snap-runtime.md b/docs/core/install/linux-snap-runtime.md new file mode 100644 index 0000000000000..26d1f27359796 --- /dev/null +++ b/docs/core/install/linux-snap-runtime.md @@ -0,0 +1,115 @@ +--- +title: Install .NET Runtime on Linux with Snap +description: Learn about how to install the .NET Runtime snap package. Canonical maintains and supports .NET-related snap packages. +author: adegeo +ms.author: adegeo +ms.date: 05/22/2024 +ms.topic: install-set-up-deploy +ms.custom: linux-related-content +#customer intent: As a Linux user, I want to install .NET Runtime through Snap. +--- + +# Install .NET Runtime with Snap + +This article describes how to install the .NET Runtime snap package. .NET Runtime snap packages are provided by and maintained by Canonical. Snaps are a great alternative to the package manager built into your Linux distribution. + +A snap is a bundle of an app and its dependencies that works across many different Linux distributions. Snaps are discoverable and installable from the Snap Store. For more information about Snap, see [Getting started with Snap](https://snapcraft.io/docs/getting-started). + +> [!CAUTION] +> Snap installations of .NET may have problems running [.NET tools](../tools/global-tools.md). If you wish to use .NET tools, we recommend that you install .NET using the [`dotnet-install` script](linux-scripted-manual.md#scripted-install) or the package manager for the particular Linux distribution. + +## Prerequisites + +- Linux distribution that supports snap. +- `snapd` the snap daemon. + +Your Linux distribution might already include snap. Try running `snap` from a terminal to see if the command works. For a list of supported Linux distributions, and instructions on how to install snap, see [Installing `snapd`](https://snapcraft.io/docs/installing-snapd). + +## .NET releases + +[!INCLUDE [supported-versions](includes/supported-versions.md)] + +## 1. Install the runtime + +The following steps install the .NET 8 runtime snap package: + +01. Open a terminal. +01. Use `snap install` to install the .NET Runtime snap package. For example, the following command installs the .NET 8 runtime. + + ```bash + sudo snap install dotnet-runtime-80 + ``` + +Each .NET Runtime is published as an individual snap package. The following table lists the packages: + +| .NET version | Snap package | .NET version supported by Microsoft | +|---------------------------------------------------|---------------------|-----| +| [8 (STS)](https://snapcraft.io/dotnet-runtime-80) | `dotnet-runtime-80` | Yes | +| [7 (STS)](https://snapcraft.io/dotnet-runtime-70) | `dotnet-runtime-70` | No | +| [6 (LTS)](https://snapcraft.io/dotnet-runtime-60) | `dotnet-runtime-60` | Yes | +| [5](https://snapcraft.io/dotnet-runtime-50) | `dotnet-runtime-50` | No | +| [3.1](https://snapcraft.io/dotnet-runtime-31) | `dotnet-runtime-31` | No | +| [3.0](https://snapcraft.io/dotnet-runtime-30) | `dotnet-runtime-30` | No | +| [2.2](https://snapcraft.io/dotnet-runtime-22) | `dotnet-runtime-22` | No | +| [2.1](https://snapcraft.io/dotnet-runtime-21) | `dotnet-runtime-21` | No | + +## 2. Enable the dotnet command + +When the .NET runtime snap package is installed, the `dotnet` command isn't automatically configured. Use the `snap alias` command to use the `dotnet` command from the terminal. The command is formatted as: `sudo snap alias {package}.{command} {alias}`. The following example maps the `dotnet` command: + +```bash +sudo snap alias dotnet-runtime-80.dotnet dotnet +``` + +## 3. Export the install location + +The `DOTNET_ROOT` environment variable is often used by tools to determine where .NET is installed. When .NET is installed through Snap, this environment variable isn't configured. You should configure the *DOTNET_ROOT* environment variable in your profile. The path to the snap uses the following format: `/snap/{package}/current`. For example, if you installed the `dotnet-runtime-80` snap, use the following command to set the environment variable to where .NET is located: + +```bash +export DOTNET_ROOT=/snap/dotnet-runtime-80/current +``` + +### Export the environment variable permanently + +The preceding `export` command only sets the environment variable for the terminal session in which it was run. + +You can edit your shell profile to permanently add the commands. There are a number of different shells available for Linux and each has a different profile. For example: + +- **Bash Shell**: *~/.bash_profile*, *~/.bashrc* +- **Korn Shell**: *~/.kshrc* or *.profile* +- **Z Shell**: *~/.zshrc* or *.zprofile* + +Edit the appropriate source file for your shell and add `export DOTNET_ROOT=/snap/dotnet-runtime-80/current`. + +## Troubleshooting + +- [The dotnet terminal command doesn't work](#the-dotnet-terminal-command-doesnt-work) +- [Can't install Snap on WSL2](#cant-install-snap-on-wsl2) + +### The dotnet terminal command doesn't work + +Snap packages can map an alias to a command provided by the package. The .NET Runtime snap packages don't automatically lias the `dotnet` command. To alias the `dotnet` command to the snap package, use the following command: + +```bash +sudo snap alias dotnet-runtime-80.dotnet dotnet +``` + +Substitute `dotnet-runtime-80` with the name of your runtime package. + +### Can't install Snap on WSL2 + +`systemd` must be enabled on the WSL2 instance before Snap can be installed. + +1. Open `/etc/wsl.conf` in a text editor of your choice. +1. Paste in the following configuration: + + ```ini + [boot] + systemd=true + ``` + +1. Save the file and restart the WSL2 instance through PowerShell. Use the `wsl.exe --shutdown` command. + +## Related content + +- [How to enable TAB completion for the .NET CLI.](../tools/enable-tab-autocomplete.md) diff --git a/docs/core/install/linux-snap-sdk.md b/docs/core/install/linux-snap-sdk.md new file mode 100644 index 0000000000000..60038d1d04f8e --- /dev/null +++ b/docs/core/install/linux-snap-sdk.md @@ -0,0 +1,171 @@ +--- +title: Install .NET SDK on Linux with Snap +description: Learn about how to install the .NET SDK snap package. Canonical maintains and supports .NET-related snap packages. +author: adegeo +ms.author: adegeo +ms.date: 05/23/2024 +ms.topic: install-set-up-deploy +ms.custom: linux-related-content +#customer intent: As a Linux user, I want to install .NET SDK through Snap. +--- + +# Install .NET SDK with Snap + +This article describes how to install the .NET SDK snap package. .NET SDK snap packages are provided by and maintained by Canonical. Snaps are a great alternative to the package manager built into your Linux distribution. + +A snap is a bundle of an app and its dependencies that works across many different Linux distributions. Snaps are discoverable and installable from the Snap Store. For more information about Snap, see [Getting started with Snap](https://snapcraft.io/docs/getting-started). + +> [!CAUTION] +> Snap installations of .NET may have problems running [.NET tools](../tools/global-tools.md). If you wish to use .NET tools, we recommend that you install .NET using the [`dotnet-install` script](linux-scripted-manual.md#scripted-install) or the package manager for the particular Linux distribution. +> +> It's a known issue that the `dotnet watch` command doesn't work when .NET is installed via Snap. +> +> If you're going to use .NET tools or the `dotnet watch` command, we recommend that you install .NET using the [`dotnet-install` script](linux-scripted-manual.md#scripted-install). + +## Prerequisites + +- Linux distribution that supports snap. +- `snapd` the snap daemon. + +Your Linux distribution might already include snap. Try running `snap` from a terminal to see if the command works. For a list of supported Linux distributions, and instructions on how to install snap, see [Installing `snapd`](https://snapcraft.io/docs/installing-snapd). + +## .NET releases + +[!INCLUDE [supported-versions](includes/supported-versions.md)] + +## 1. Install the SDK + +Snap packages for the .NET SDK are all published under the same identifier: `dotnet-sdk`. A specific version of the SDK can be installed by specifying the channel. The SDK includes both the ASP.NET Core and .NET runtime, versioned to the SDK. + +> [!TIP] +> The [Snapcraft .NET SDK package page](https://snapcraft.io/dotnet-sdk) includes distribution-specific instructions on how to install Snapcraft and .NET. + +01. Open a terminal. +01. Use `snap install` to install the .NET SDK snap package. For example, the following command installs the `latest/stable` channel, which is the default. + + ```bash + sudo snap install dotnet-sdk --classic + ``` + + - The `--classic` parameter is required. + - Use the `--channel` parameter to specify which version to install. If this parameter is omitted, `latest/stable` is used. For example, `--channel 8.0/stable` installs .NET SDK 8.0. + +The `dotnet` snap alias is automatically created and mapped to the snap package's `dotnet` command. + +The following table lists the package channels you can install: + +| .NET version | Snap package channel | +|--------------|--------------------------| +| 8 (LTS) | `8.0/stable`
`latest/stable`
`lts/stable` | +| 7 | `7.0/stable` (out of support) | +| 6 (LTS) | `6.0/stable` | +| 5 | `5.0/stable` (out of support) | +| 3.1 | `3.1/stable` (out of support) | +| 2.1 | `2.1/stable` (out of support) | + +## 2. Export the install location + +The `DOTNET_ROOT` environment variable is often used by tools to determine where .NET is installed. When .NET is installed through Snap, this environment variable isn't configured. You should configure the *DOTNET_ROOT* environment variable in your profile. The path to the snap uses the following format: `/snap/{package}/current`. + +```bash +export DOTNET_ROOT=/snap/dotnet-sdk/current +``` + +### Export the environment variable permanently + +The preceding `export` command only sets the environment variable for the terminal session in which it was run. + +You can edit your shell profile to permanently add the commands. There are many different shells available for Linux and each has a different profile. For example: + +- **Bash Shell**: _~/.bash_profile_, _~/.bashrc_ +- **Korn Shell**: _~/.kshrc_ or _.profile_ +- **Z Shell**: _~/.zshrc* or _.zprofile_ + +Edit the appropriate source file for your shell and add `export DOTNET_ROOT=/snap/dotnet-sdk/current`. + +## Troubleshooting + +- [The dotnet terminal command doesn't work](#the-dotnet-terminal-command-doesnt-work) +- [Can't install Snap on WSL2](#cant-install-snap-on-wsl2) +- [Can't resolve the dotnet command or SDK](#cant-resolve-the-dotnet-command-or-sdk) +- [TLS/SSL Certificate errors](#tlsssl-certificate-errors) + +### The dotnet terminal command doesn't work + +Snap packages can map an alias to a command provided by the package. By default, the .NET SDK snap packages create an alias for the `dotnet` command. If the alias wasn't created or was previously removed, the following command shows how to map the alias: + +```bash +sudo snap alias dotnet-sdk.dotnet dotnet +``` + +### Can't install Snap on WSL2 + +`systemd` must be enabled on the WSL2 instance before Snap can be installed. + +01. Open `/etc/wsl.conf` in a text editor of your choice. +01. Paste in the following configuration: + + ```ini + [boot] + systemd=true + ``` + +01. Save the file and restart the WSL2 instance through PowerShell. Use the `wsl.exe --shutdown` command. + +### Can't resolve the dotnet command or SDK + +It's common for other apps, such as a code IDE or an extension in Visual Studio Code, to try to resolve the location of the .NET SDK. Typically, discovery is done by checking the `DOTNET_ROOT` environment variable, or figuring out where the `dotnet` executable is located. A snap-installed .NET SDK might confuse these apps. When these apps can't resolve the .NET SDK, an error similar to one of the following messages is displayed: + +- The SDK 'Microsoft.NET.Sdk' specified could not be found +- The SDK 'Microsoft.NET.Sdk.Web' specified could not be found +- The SDK 'Microsoft.NET.Sdk.Razor' specified could not be found + +Try the following steps to fix the issue: + +01. Making sure that you [export the `DOTNET_ROOT` environment variable permanently](#export-the-environment-variable-permanently). + +01. Try to symbolic link the snap `dotnet` executable to the location that the program is looking for. + + Two common paths the `dotnet` command is looking for are: + + - `/usr/local/bin/dotnet` + - `/usr/share/dotnet` + + Use the following command to create a symbolic link to the snap package: + + ```bash + ln -s /snap/dotnet-sdk/current/dotnet /usr/local/bin/dotnet + ``` + +### TLS/SSL Certificate errors + +When .NET is installed through Snap, it's possible that on some distributions the .NET TLS/SSL certificates might not be found and you might receive an error during `restore`: + +```bash +Processing post-creation actions... +Running 'dotnet restore' on /home/myhome/test/test.csproj... + Restoring packages for /home/myhome/test/test.csproj... +/snap/dotnet-sdk/27/sdk/2.2.103/NuGet.targets(114,5): error : Unable to load the service index for source https://api.nuget.org/v3/index.json. [/home/myhome/test/test.csproj] +/snap/dotnet-sdk/27/sdk/2.2.103/NuGet.targets(114,5): error : The SSL connection could not be established, see inner exception. [/home/myhome/test/test.csproj] +/snap/dotnet-sdk/27/sdk/2.2.103/NuGet.targets(114,5): error : The remote certificate is invalid according to the validation procedure. [/home/myhome/test/test.csproj] +``` + +To resolve this problem, set a few environment variables: + +```bash +export SSL_CERT_FILE=[path-to-certificate-file] +export SSL_CERT_DIR=/dev/null +``` + +The certificate location varies by distribution. Here are the locations for the distributions where the issue has been observed: + +| Distribution | Location | +|--------------|-----------------------------------------------------| +| **Fedora** | `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem` | +| **OpenSUSE** | `/etc/ssl/ca-bundle.pem` | +| **Solus** | `/etc/ssl/certs/ca-certificates.crt` | + +## Related content + +- [How to enable TAB completion for the .NET CLI.](../tools/enable-tab-autocomplete.md) +- [Tutorial: Create a console application with .NET SDK using Visual Studio Code](../tutorials/with-visual-studio-code.md) diff --git a/docs/core/install/linux.md b/docs/core/install/linux.md index b47ae4508761b..d106a9829b929 100644 --- a/docs/core/install/linux.md +++ b/docs/core/install/linux.md @@ -1,6 +1,6 @@ --- title: Install .NET on Linux distributions -description: Learn about how to install .NET on Linux. .NET is not only available at package.microsoft.com, but also the official package archives for various Linux distributions. +description: Learn about how .NET is available on Linux. .NET can be installed through a package manager, a snap package, or manually. author: adegeo ms.author: adegeo ms.custom: updateeachrelease, linux-related-content @@ -15,16 +15,7 @@ ms.date: 12/15/2023 > - [Install on macOS](macos.md) > - [Install on Linux](linux.md) -This article details how to install .NET on various Linux distributions either manually, via a package manager, or via a [container](../docker/introduction.md#net-images). - -## Manual installation - -You can install .NET manually in the following ways: - -- [Manual install](linux-scripted-manual.md#manual-install) -- [Scripted install](linux-scripted-manual.md#scripted-install) - -You may need to install [.NET dependencies](https://github.com/dotnet/core/blob/main/release-notes/8.0/linux-packages.md) if you install .NET manually. +This article describes how .NET is available on various Linux distributions. .NET can be installed by a package manager, snap, or manually. .NET is also available as a [container image](../docker/introduction.md#net-images). ## Packages @@ -40,8 +31,18 @@ You may need to install [.NET dependencies](https://github.com/dotnet/core/blob/ .NET is [supported by Microsoft](https://github.com/dotnet/core/blob/main/microsoft-support.md) when downloaded from a Microsoft source. Best effort support is offered from Microsoft when downloaded from elsewhere. You can open issues at [dotnet/core](https://github.com/dotnet/core) if you run into problems. -## Next steps +## Snap + +.NET SDK snap packages are provided by and maintained by Canonical. Snaps are a great alternative to the package manager built into your Linux distribution. -- [How to check if .NET is already installed](how-to-detect-installed-versions.md?pivots=os-linux). -- [Tutorial: Create a new app with Visual Studio Code](../tutorials/with-visual-studio-code.md). -- [Tutorial: Containerize a .NET app](../docker/build-container.md). +- [Install .NET Runtime with Snap](linux-snap-runtime.md) +- [Install .NET SDK with Snap](linux-snap-sdk.md) + +## Manual installation + +You can install .NET manually in the following ways: + +- [Manual install](linux-scripted-manual.md#manual-install) +- [Scripted install](linux-scripted-manual.md#scripted-install) + +You may need to install [.NET dependencies](https://github.com/dotnet/core/blob/main/release-notes/8.0/linux-packages.md) if you install .NET manually. diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 460411de9389a..3561070495aa2 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -45,6 +45,12 @@ items: href: ../core/install/linux-sles.md - name: Installation script & binaries href: ../core/install/linux-scripted-manual.md + - name: Install with Snap + items: + - name: Runtime + href: ../core/install/linux-snap-runtime.md + - name: SDK + href: ../core/install/linux-snap-sdk.md - name: Upgrade to a new .NET version href: ../core/install/upgrade.md - name: Remove outdated runtimes and SDKs