diff --git a/docs/core/versions/index.md b/docs/core/versions/index.md index 92b7dd83a473f..cc74205f0099b 100644 --- a/docs/core/versions/index.md +++ b/docs/core/versions/index.md @@ -3,129 +3,41 @@ title: .NET Core versioning description: Understand how .NET Core versioning works. author: bleroy ms.author: mairaw -ms.date: 02/13/2018 +ms.date: 07/26/2018 --- # .NET Core versioning -.NET Core is made of [NuGet packages](../packages.md), tools, and frameworks that are distributed as a unit. Each of these platform layers can be versioned separately, enabling better agility. While there is significant versioning flexibility in that regard, there's also a desire to version the platform as a unit to make the product easier to understand. +.NET Core refers to the .NET Core Runtime and the .NET Core SDK, which contains the tools you need to develop applications. .NET Core SDKs are designed to work with any previous version of the .NET Core Runtime. This article explains the runtime and the SDK version strategy. An explanation of version numbers for .NET Standard can be found in the article introducing [.NET Standard](../../standard/net-standard.md#net-implementation-support). -This article aims at clarifying how the .NET Core SDK and runtime are versioned. - -There are lots of moving parts that version independently in .NET Core. However, starting with .NET Core 2.0, there is an easy to understand top-level version number that everybody understands to be *the* version of ".NET Core" as a whole. The rest of this document goes into the details of the versioning of all those parts. These details can be important if you're a package manager, for example. - -> [!IMPORTANT] -> The versioning details explained on this topic don't apply to the current version of the .NET Core SDK and runtime. -> The version scheme is changing in future releases. You can see the current proposal at the [dotnet/designs](https://github.com/dotnet/designs/pull/29) repository. +The .NET Core Runtime and .NET Core SDK add new features at a different rate - in general the .NET Core SDK provides updated tools more quickly than the .NET Core Runtime changes the runtime you use in production. Unfortunately, this problem has resulted in several versioning strategies over the last few years. You can learn about the history in the article on [.NET Core versioning](version-history.md). ## Versioning details -With .NET Core 2.0, downloads show a single version number in their file name. The following version numbers were unified: - -* The shared framework and associated runtime. -* The .NET Core SDK and associated .NET Core CLI. -* The `Microsoft.NETCore.App` metapackage. - -The use of a single version number makes it easier for users to know what version of the SDK to install on their dev machines, and what the corresponding version of the shared framework should be when time comes to provision a production environment. When downloading an SDK or runtime, the version number you see is going to be the same. - -### Version selection - -.NET Core applies a set of policies that determine which versions of the .NET Core runtime and SDK are used in various scenarios. These scenarios and policies are fully explored in the article on [version selection](selection.md). - -You can think of these policies as performing the following roles: - -* Enable easy and efficient deployment of .NET Core, including security and reliability updates. -* Enable developers to use the latest tools and commands independent of target runtime. - -### Installers - -With .NET Core 2.0, downloads for the [daily builds](https://github.com/dotnet/core-setup#daily-builds) and [releases](https://www.microsoft.com/net/download/core) adhere to a new naming scheme that is easier to understand. -The installer UI in those downloads was also modified to clearly present the names and versions of the components being installed. In particular, titles now show the same version number that is in the download's file name. - -#### File name format - -`[product]-[component]-[major].[minor].[patch]-[previewN]-[optional build #]-[rid].[file ext]` - -Here are some examples of this format: - -``` -dotnet-runtime-2.0.4-osx.10.12-x64.pkg # Mac runtime installer -dotnet-sdk-2.0.4-win-x64.exe # Windows SDK installer -dotnet-sdk-2.0.4-linux-x64.tar.gz # Linux binary archive - -#Ubuntu file set needed for the SDK -dotnet-host-2.0.4-ubuntu.16.04-x64.deb # Host / muxer and host policy -dotnet-runtime-2.0.4-ubuntu.16.04-x64.deb # runtime -dotnet-sdk-2.0.4-ubuntu.16.04-x64.deb # SDK tools -``` - -The format is readable and clearly shows what you're downloading, what version it is, and where you can use it. The runtime package name includes `runtime`, and the SDK includes `SDK`. - -#### UI string format +".NET Core 2.1" refers to the .NET Core Runtime version number. The .NET Core Runtime has a major/minor/patch approach to versioning that follows [semantic versioning](#semantic-versioning). -All web site descriptions and UI strings in the installers are kept consistent, accurate, and simple. The following table shows some examples: +The .NET Core SDK doesn't follow semantic versioning. The .NET Core SDK releases faster and its versions must communicate both the aligned runtime and the SDK's own minor and patch releases. The first two positions of the .NET Core SDK version are locked to the .NET Core Runtime it released with. Each version of the SDK can create applications for this runtime or any lower version. -| Installer | Window Title | Other content in installer | What is installed | -| :-- | :-- | :-- | :-- | -| SDK | .NET Core 2.0 SDK (x64) Installer | .NET Core 2.0.4 SDK | .NET Core 2.0.4 Tools + .NET Core 2.0.4 Runtime | -| Runtime | .NET Core 2.0 Runtime (x64) Installer | .NET Core 2.0.4 Runtime | .NET Core 2.0.4 Runtime | +The third position of the SDK version number communicates both the minor and patch number. The minor version is multiplied by 100. Minor version 1, patch version 2 would be represented as 102. The final two digits represent the patch number. For example, the release of .NET Core 2.2 may create releases like the following table: -Preview releases differ only slightly: +| Change | .NET Core Runtime | .NET Core SDK (*) | +|-----------------------|-------------------|-------------------| +| Initial release | 2.2.0 | 2.2.100 | +| SDK Patch | 2.2.0 | 2.2.101 | +| Runtime and SDK Patch | 2.2.1 | 2.2.102 | +| SDK Feature change | 2.2.1 | 2.2.200 | -| Installer | Window Title | Other content in installer | What is installed | -| :-- | :-- | :-- | :-- | -| SDK | .NET Core 2.0 Preview 1 SDK (x64) Installer | .NET Core 2.0.0 Preview 1 SDK | .NET Core 2.0.0 Preview 1 Tools + .NET Core 2.0.0 Preview 1 Runtime | -| Runtime | .NET Core 2.0 Preview 1 Runtime (x64) Installer | .NET Core 2.0.0 Preview 1 Runtime | .NET Core 2.0.0 Preview 1 Runtime | +(\*) This chart uses a future 2.2 .NET Core Runtime as the example because a historic artifact meant the first SDK for .NET Core 2.1 is 2.1.300. For more information, See the [history of .NET Core versioning](version-history.md). -It may happen that an SDK release contains more than one version of the runtime. When that happens, the installer UX looks like the following (only the SDK version is shown and the installed Runtime versions are shown on a summary page at the end of the installation process on Windows and Mac): +NOTES: -| Installer | Window Title | Other content in installer | What is installed | -| :-- | :-- | :-- | :-- | -| SDK | .NET Core 2.1 SDK (x64) Installer | .NET Core 2.1.1 SDK
.NET Core 2.1.1 Runtime
.NET Core 2.0.6 Runtime | .NET Core 2.1.1 Tools + .NET Core 2.1.1 Runtime + .NET Core 2.0.6 Runtime | +* If the SDK has 10 feature updates before a runtime feature update, version numbers roll into the 1000 series with numbers like 2.2.1000 as the feature release following 2.2.900. This situation isn't expected to occur. +* 99 patch releases without a feature release won't occur. If a release approaches this number, it forces a feature release. -It's also possible that .NET Core Tools need to be updated, without runtime changes. In that case, the SDK version is increased (for example, to 2.1.2) and then the Runtime catches up the next time it ships (for example, both the Runtime and SDK ship the next time as 2.1.3). +You can see more details in the initial proposal at the [dotnet/designs](https://github.com/dotnet/designs/pull/29) repository. -### Package managers +## Semantic versioning -.NET Core can be distributed by other entities than Microsoft. In particular, Linux distribution owners and package maintainers may add .NET Core packages to their package managers. For recommendations on how those packages should be named and versioned, see [.NET Core distribution packaging](../build/distribution-packaging.md). - -#### Minimum package set - -* `dotnet-runtime-[major].[minor]`: a runtime with the specified version (only the latest patch version for a given major+minor combination should be available in the package manager). New patch versions update the package, but new minor or major versions are separate packages. - - **Dependencies**: `dotnet-host` - -* `dotnet-sdk`: the latest SDK. `update` rolls forward major, minor, and patch versions. - - **Dependencies**: the latest `dotnet-sdk-[major].[minor]`. - -* `dotnet-sdk-[major].[minor]`: the SDK with the specified version. The version specified is the highest included version of included shared frameworks, so that users can easily relate an SDK to a shared framework. New patch versions update the package, but new minor or major versions are separate packages. - - **Dependencies**: `dotnet-host`, one or more `dotnet-runtime-[major].[minor]` (one of those is used by the SDK code itself, the others are here for users to build and run against). - -* `dotnet-host`: the latest host. - -##### Preview versions - -Package maintainers may decide to include preview versions of the runtime and SDK. Don't include those preview versions in the unversioned `dotnet-sdk` package, but you can release them as versioned packages with an additional preview marker appended to the major and minor version sections of the name. For example, there may be a `dotnet-sdk-2.0-preview1-final` package. - -### Docker - -A general Docker tag naming convention is to place the version number before the component name. This convention may continue to be utilized. The current tags include only the Runtime version as follows. - -* 1.0.8-runtime -* 1.0.8-sdk -* 2.0.4-runtime -* 2.0.4-sdk -* 2.1.1-runtime -* 2.1.1-sdk - -The SDK tags should be updated to represent the SDK version rather than Runtime. - -It's also possible that the .NET Core CLI tools (included in the SDK) are fixed but reship with an existing runtime. In that case, the SDK version is increased (for example, to 2.1.2), and then the Runtime catches up the next time it ships (for example, both the Runtime and SDK ship the following time as 2.1.3). - -## Semantic Versioning - -.NET Core uses [Semantic Versioning (SemVer)](http://semver.org/), adopting the use of `MAJOR.MINOR.PATCH` versioning, using the various parts of the version number to describe the degree and type of change. +The .NET Core *Runtime* roughly adheres to [Semantic Versioning (SemVer)](http://semver.org/), adopting the use of `MAJOR.MINOR.PATCH` versioning, using the various parts of the version number to describe the degree and type of change. ``` MAJOR.MINOR.PATCH[-PRERELEASE-BUILDNUMBER] @@ -133,30 +45,35 @@ MAJOR.MINOR.PATCH[-PRERELEASE-BUILDNUMBER] The optional `PRERELEASE` and `BUILDNUMBER` parts are never part of supported releases and only exist on nightly builds, local builds from source targets, and unsupported preview releases. -### How version numbers are incremented? +### Understand runtime version number changes `MAJOR` is incremented when: -- An old version is no longer supported. -- A newer `MAJOR` version of an existing dependency is adopted. -- The default setting of a compatibility quirk is changed to "off." +* Significant changes occur to the product, or a new product direction. +* Breaking changes were taken. There's a high bar to accepting breaking changes. +* An old version is no longer supported. +* A newer `MAJOR` version of an existing dependency is adopted. `MINOR` is incremented when: -- Public API surface area is added. -- A new behavior is added. -- A newer `MINOR` version of an existing dependency is adopted. -- A new dependency is introduced. +* Public API surface area is added. +* A new behavior is added. +* A newer `MINOR` version of an existing dependency is adopted. +* A new dependency is introduced. `PATCH` is incremented when: -- Bug fixes are made. -- Support for a newer platform is added. -- A newer `PATCH` version of an existing dependency is adopted. -- Any other change doesn't fit one of the previous cases. +* Bug fixes are made. +* Support for a newer platform is added. +* A newer `PATCH` version of an existing dependency is adopted. +* Any other change doesn't fit one of the previous cases. When there are multiple changes, the highest element affected by individual changes is incremented, and the following ones are reset to zero. For example, when `MAJOR` is incremented, `MINOR` and `PATCH` are reset to zero. When `MINOR` is incremented, `PATCH` is reset to zero while `MAJOR` is left untouched. +## Version numbers in file names + +The files downloaded for .NET Core carry the version, for example, `dotnet-sdk-2.1.300-win10-x64.exe`. + ### Preview versions Preview versions have a `-preview[number]-([build]|"final")` appended to the version. For example, `2.0.0-preview1-final`. @@ -165,96 +82,21 @@ Preview versions have a `-preview[number]-([build]|"final")` appended to the ver After a release goes out, the release branches generally stop producing daily builds and instead start producing servicing builds. Servicing versions have a `-servicing-[number]` appended to the version. For example, `2.0.1-servicing-006924`. -### LTS vs. current - -There are two trains of releases for .NET Core: Long Term Support (LTS) and Current. That enables users to pick the level of stability and new features they want, while still being supported. - -- LTS means you get new features less frequently, but you have a more mature platform. LTS also has a longer period of support. -- Current means you get new features and APIs more frequently, but the disadvantage is that you have a shorter window of time to install updates, and those updates happen more frequently. Current is also fully supported but the support period is shorter than LTS. - -A "Current" version may get promoted to LTS. - -"LTS" and "Current" should be considered as labels that we put on specific releases to make a statement about the associated level of support. - -For more information, see [.NET Core Support Lifecycle Fact Sheet](https://www.microsoft.com/net/core/support). - -## Versioning scheme details - -.NET Core is made of the following parts: - -- A host: either *dotnet.exe* for framework-dependent applications, or *\.exe* for self-contained applications. -- An SDK (the set of tools necessary on a developer's machine, but not in production). -- A runtime. -- A shared framework implementation, distributed as packages. Each package is versioned independently, particularly for patch versioning. -- Optionally, a set of [metapackages](../packages.md) that reference fine-grained packages as a versioned unit. Metapackages can be versioned separately from packages. - -.NET Core also includes a set of target frameworks (for example, `netstandard` or `netcoreapp`) that represent a progressively larger API set, as version numbers are incremented. - -### .NET Standard - -.NET Standard has been using a `MAJOR.MINOR` versioning scheme. `PATCH` level isn't useful for .NET Standard because it expresses a set of contracts that are iterated on less often and doesn't present the same requirements for versioning as an actual implementation. - -There is no real coupling between .NET Standard versions and .NET Core versions: .NET Core 2.0 happens to implement .NET Standard 2.0, but there is no guarantee that future versions of .NET Core will map to the same .NET Standard version. .NET Core can ship APIs that aren't defined by .NET Standard, and, as such, may ship new versions without requiring a new .NET Standard. .NET Standard is also a concept that applies to other targets, such as .NET Framework or Mono, even if its inception happened to coincide with that of .NET Core. - -### Packages - -Library packages evolve and version independently. Packages that overlap with .NET Framework System.\* assemblies typically use 4.x versions, aligning with the .NET Framework 4.x versioning (a historical choice). Packages that do not overlap with the .NET Framework libraries (for example, [`System.Reflection.Metadata`](https://www.nuget.org/packages/System.Reflection.Metadata)) typically start at 1.0 and increment from there. - -The packages described by [`NETStandard.Library`](https://www.nuget.org/packages/NETStandard.Library) are treated specially due to being at the base of the platform. - -`NETStandard.Library` packages will typically version as a set, since they have implementation-level dependencies between them. - -### Metapackages - -Versioning for .NET Core metapackages is based on the .NET Core version they are a part of. - -For instance, the metapackages in .NET Core 2.1.3 should all have 2.1 as their `MAJOR` and `MINOR` version numbers. - -The patch version for the metapackage is incremented every time any referenced package is updated. Patch versions don't include an updated framework version. As a result, the metapackages aren't strictly SemVer-compliant because their versioning scheme doesn't represent the degree of change in the underlying packages, but primarily of the API level. - -There are currently two primary metapackages for .NET Core: - -**Microsoft.NETCore.App** - -- v1.0 as of .NET Core 1.0 (these versions match). -- Maps to the `netcoreapp` framework. -- Describes the packages in the .NET Core distribution. - -Note: [`Microsoft.NETCore.Portable.Compatibility`](https://www.nuget.org/packages/Microsoft.NETCore.Portable.Compatibility) is another .NET Core metapackage that exists to enable compatibility with pre-.NET Standard implementation of .NET. It doesn't map to a particular framework, so it versions like a package. - -**NETStandard.Library** - -[`NETStandard.Library`](https://www.nuget.org/packages/NETStandard.Library) describes the libraries that are part of the [.NET Standard](../../standard/library.md). Applies to all .NET implementations that support .NET Standard, such as .NET Framework, .NET Core, and Mono. - -### Target frameworks - -Target framework versions are updated when new APIs are added. They have no concept of patch version, since they represent API shape and not implementation concerns. Major and minor versioning follows the SemVer rules specified earlier, and coincides with the `MAJOR` and `MINOR` numbers of the .NET Core distributions that implement them. - -## Versioning in practice - -When you download .NET Core, the name of the downloaded file carries the version, for example, `dotnet-sdk-2.0.4-win10-x64.exe`. - -There are commits and pull requests on .NET Core repos on GitHub on a daily basis, resulting in new builds of many libraries. It isn't practical to create new public versions of .NET Core for every change. Instead, changes are aggregated over an undetermined period of time (for example, weeks or months) before making a new public stable .NET Core version. - -A new version of .NET Core could mean several things: - -- New versions of packages and metapackages. -- New versions of various frameworks, assuming the addition of new APIs. -- New version of the .NET Core distribution. - -### Shipping a patch release - -After shipping a major release of .NET Core, such as version 2.0.0, patch-level changes are made to .NET Core libraries to fix bugs and improve performance and reliability. That means that no new APIs are introduced. The various metapackages are updated to reference the updated .NET Core library packages. The metapackages are versioned as patch updates (`MAJOR.MINOR.PATCH`). Target frameworks are never updated as part of patch releases. A new .NET Core distribution is released with a version number that matches that of the `Microsoft.NETCore.App` metapackage. +## Relationship to .NET Standard versions -### Shipping a minor release +.NET Standard consists of a .NET reference assembly. There are multiple implementations specific to each platform. The reference assembly contains the definition of .NET all the versions of .NET Standard. Each implementation fulfills the .NET Standard contract on the specific platform. .NET Standard usually refers to the reference library. You can learn more about .NET Standard in the article on [.NET Standard](../../standard/net-standard.md) in the .NET Guide. -After shipping a .NET Core version with an incremented `MAJOR` version number, new APIs are added to .NET Core libraries to enable new scenarios. The various metapackages are updated to reference the updated .NET Core library packages. The metapackages are versioned as patch updates with `MAJOR` and `MINOR` version numbers matching the new framework version. New target framework names with the new `MAJOR.MINOR` version are added to describe the new APIs (for example, `netcoreapp2.1`). A new .NET Core distribution is released with a matching version number to the `Microsoft.NETCore.App` metapackage. +The .NET Standard reference implementation uses a `MAJOR.MINOR` versioning scheme. `PATCH` level isn't useful for .NET Standard because if exposes only an API (no implementation) and by definition any change to the API would represent a change in the feature set, and thus a new `MINOR` version. -### Shipping a major release +The implementations on each runtime may be updated, typically as part of the runtime release, and thus not evident to the programmers using .NET Standard on that platform. -Every time a new major version of .NET Core ships, the `MAJOR` version number gets incremented, and the `MINOR` version number gets reset to zero. The new major version contains at least all the APIs that were added by minor releases after the previous major version. A new major version should enable important new scenarios, and it may also drop support for an older platform. +Each version of .NET Core implements a version of .NET standard. Implementing a version of .NET Standard implies support for previous versions of .NET Standard. .NET Standard and .NET Core version independently. It's a coincidence that .NET Core 2.0 implements .NET Standard 2.0. .NET Core 2.1 also implements .NET Standard 2.0. .NET Core will support future versions of .NET Standard as they become available. -The various metapackages are updated to reference the updated .NET Core library packages. The [`Microsoft.NETCore.App`](https://www.nuget.org/packages/Microsoft.NETCore.App) metapackage and the `netcore` target framework are versioned as a major update matching the `MAJOR` version number of the new release. +| .NET Core | .NET Standard | +|-----------|---------------| +| 1.0 | up to 1.6 | +| 2.0 | up to 2.0 | +| 2.1 | up to 2.0 | ## See also @@ -262,3 +104,4 @@ The various metapackages are updated to reference the updated .NET Core library [.NET Core distribution packaging](../build/distribution-packaging.md) [.NET Core Support Lifecycle Fact Sheet](https://www.microsoft.com/net/core/support) [.NET Core 2+ Version Binding](https://github.com/dotnet/designs/issues/3) +[Docker images for .NET Core](https://hub.docker.com/r/microsoft/dotnet/) diff --git a/docs/core/versions/media/remove-runtime-sdk-versions/programs-and-features.png b/docs/core/versions/media/remove-runtime-sdk-versions/programs-and-features.png new file mode 100644 index 0000000000000..6597b1cb5884c Binary files /dev/null and b/docs/core/versions/media/remove-runtime-sdk-versions/programs-and-features.png differ diff --git a/docs/core/versions/remove-runtime-sdk-versions.md b/docs/core/versions/remove-runtime-sdk-versions.md new file mode 100644 index 0000000000000..cda56bd8a284f --- /dev/null +++ b/docs/core/versions/remove-runtime-sdk-versions.md @@ -0,0 +1,190 @@ +--- +title: How to remove .NET runtime and SDK +description: Instructions for removing the .NET Core Runtime and SDK components on Windows, Mac, and Linux +ms.date: 07/28/2018 +author: billwagner +ms.author: wiwagn +--- +# How to remove the .NET Core Runtime and SDK + +Over time, as you install updated versions of the .NET Core runtime and SDK, you may want to remove outdated versions of .NET Core from your machine. Removing older versions of the runtime may change the runtime chosen to run shared framework applications, as detailed in the article on [.NET Core version selection](selection.md). + +Starting with .NET Core 2.1, the .NET CLI has options you can use to list the versions of the SDK and runtime that are installed on your machine. Use [`dotnet --list-sdks`](../tools/dotnet.md#options) to see the list of SDKs installed on your machine. Use [`dotnet --list-runtimes`](../tools/dotnet.md#options) to see the list of runtimes installed on your machine. The following text shows typical output for Windows, macOS, or Linux: + +# [Windows](#tab/Windows) + +```console +C:\> dotnet --list-sdks +2.1.200-preview-007474 [C:\Program Files\dotnet\sdk] +2.1.200-preview-007480 [C:\Program Files\dotnet\sdk] +2.1.200-preview-007509 [C:\Program Files\dotnet\sdk] +2.1.200-preview-007570 [C:\Program Files\dotnet\sdk] +2.1.200-preview-007576 [C:\Program Files\dotnet\sdk] +2.1.200-preview-007587 [C:\Program Files\dotnet\sdk] +2.1.200-preview-007589 [C:\Program Files\dotnet\sdk] +2.1.200 [C:\Program Files\dotnet\sdk] +2.1.201 [C:\Program Files\dotnet\sdk] +2.1.202 [C:\Program Files\dotnet\sdk] +2.1.300-preview2-008533 [C:\Program Files\dotnet\sdk] +2.1.300 [C:\Program Files\dotnet\sdk] +2.1.400-preview-009063 [C:\Program Files\dotnet\sdk] +2.1.400-preview-009088 [C:\Program Files\dotnet\sdk] +2.1.400-preview-009171 [C:\Program Files\dotnet\sdk] + +C:\> dotnet --list-runtimes +Microsoft.AspNetCore.All 2.1.0-preview2-final [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All] +Microsoft.AspNetCore.All 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All] +Microsoft.AspNetCore.All 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All] +Microsoft.AspNetCore.All 2.1.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All] +Microsoft.AspNetCore.App 2.1.0-preview2-final [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App] +Microsoft.AspNetCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App] +Microsoft.AspNetCore.App 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App] +Microsoft.AspNetCore.App 2.1.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App] +Microsoft.NETCore.App 2.0.6 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.7 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.9 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.0-preview2-26406-04 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.0 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.2 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App] +``` + +# [Linux](#tab/Linux) + +```console +$ dotnet --list-sdks +1.0.1 [/usr/share/dotnet/sdk] +1.0.4 [/usr/share/dotnet/sdk] +2.0.0-preview1-005977 [/usr/share/dotnet/sdk] +2.0.0-preview2-006497 [/usr/share/dotnet/sdk] +2.0.0 [/usr/share/dotnet/sdk] +2.1.4 [/usr/share/dotnet/sdk] +2.1.300-preview2-008530 [/usr/share/dotnet/sdk] +2.1.300 [/usr/share/dotnet/sdk] +2.1.301 [/usr/share/dotnet/sdk] + +$ dotnet --list-runtimes +Microsoft.AspNetCore.All 2.1.0-preview2-final [/usr/share/dotnet/shared/Microsoft.AspNetCore.All] +Microsoft.AspNetCore.All 2.1.0 [/usr/share/dotnet/shared/Microsoft.AspNetCore.All] +Microsoft.AspNetCore.All 2.1.1 [/usr/share/dotnet/shared/Microsoft.AspNetCore.All] +Microsoft.AspNetCore.App 2.1.0-preview2-final [/usr/share/dotnet/shared/Microsoft.AspNetCore.App] +Microsoft.AspNetCore.App 2.1.0 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App] +Microsoft.AspNetCore.App 2.1.1 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App] +Microsoft.NETCore.App 1.0.4 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 1.0.5 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 1.1.1 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 1.1.2 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.0-preview1-002111-00 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.0-preview2-25407-01 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.0 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.5 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.0-preview2-26406-04 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.0 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.1 [/usr/share/dotnet/shared/Microsoft.NETCore.App] +``` + +# [macOS](#tab/macOS) + +```console +$ dotnet --list-sdks +1.0.1 [/usr/local/share/dotnet/sdk] +1.0.4 [/usr/local/share/dotnet/sdk] +2.0.0-preview1-005977 [/usr/local/share/dotnet/sdk] +2.0.0-preview2-006497 [/usr/local/share/dotnet/sdk] +2.0.0 [/usr/local/share/dotnet/sdk] +2.1.4 [/usr/local/share/dotnet/sdk] +2.1.300-preview2-008530 [/usr/local/share/dotnet/sdk] +2.1.300 [/usr/local/share/dotnet/sdk] +2.1.301 [/usr/local/share/dotnet/sdk] + +$ dotnet --list-runtimes +Microsoft.AspNetCore.All 2.1.0-preview2-final [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All] +Microsoft.AspNetCore.All 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All] +Microsoft.AspNetCore.All 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.All] +Microsoft.AspNetCore.App 2.1.0-preview2-final [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App] +Microsoft.AspNetCore.App 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App] +Microsoft.AspNetCore.App 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.AspNetCore.App] +Microsoft.NETCore.App 1.0.4 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 1.0.5 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 1.1.1 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 1.1.2 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.0-preview1-002111-00 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.0-preview2-25407-01 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.0 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.0.5 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.0-preview2-26406-04 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.0 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +Microsoft.NETCore.App 2.1.1 [/usr/local/share/dotnet/shared/Microsoft.NETCore.App] +``` + +*** + +## Uninstalling .NET Core + +# [Windows](#tab/Windows) + +.NET Core uses the Windows **Add/Remove Programs** dialog to remove versions of the .NET Core runtime and SDK. The following figure shows the **Add/Remove Programs** dialog with several versions of the .NET runtime and SDK installed. + +![Add / Remove programs to remove .NET Core](./media/remove-runtime-sdk-versions/programs-and-features.png) + +Select any versions you want to remove from your machine and click **Uninstall**. + +# [Linux](#tab/Linux) + +There are more options to uninstall .NET Core (either SDK or runtime) on Linux. The best way for you to uninstall .NET Core is to mirror the action you used to install .NET Core. The specifics depend on your chosen distribution and the installation method. + +> [!IMPORTANT] +> For Red Hat installations, consult the [Red Hat Getting Started Guide](https://access.redhat.com/documentation/en-us/net_core/2.0/html/getting_started_guide/gs_install_dotnet#install_register_rehel) for information on installing and uninstalling .NET Core. + +Starting with .NET Core 2.1, there is no need to uninstall the .NET Core SDK when upgrading it using a package manager. The package manager `update` or `refresh` commands will automatically remove the older version upon the successful installation of a newer version. + +If you installed .NET Core using a package manager, you use that same package manager to uninstall .NET SDK or runtime. .NET Core installations support most popular package managers. Consult the documentation for your distribution's package manager for the precise syntax on your environment: + +- [apt-get(8)](https://linux.die.net/man/8/apt-get) is used by Debian based systems, including Ubuntu. +- [yum(8)](https://linux.die.net/man/8/yum) is used on Fedora, CentOS, and Oracle Linux. +- [zypper(8)](https://en.opensuse.org/SDB:Zypper_manual_(plain)) is used on openSUSE and SUSE Linux Enterprise System (SLES). +- [dnf(8)](https://dnf.readthedocs.io/latest/command_ref.html) is used on Fedora. + +In almost all cases, the command to remove a package is `remove`. + +The package name for the .NET Core SDK installation for most package managers is `dotnet-sdk`, followed by the version number. Starting with the version 2.1.300 of the .NET Core SDK and version `2.1` of the runtime, only the major and minor version numbers are necessary: for example, the .NET Core SDK version 2.1.300 can be referenced as the package `dotnet-sdk-2.1`. Prior versions require the entire version string: for example, `dotnet-sdk-2.1.200` would be required for version 2.1.200 of the .NET Core SDK. + +For machines that have installed only the runtime, and not the SDK, the package name is `dotnet-runtime-` for the .NET Core runtime, and `aspnetcore-runtime-` for the entire runtime stack. + +.NET Core installations prior to 2.0 did not uninstall the host application when the SDK was uninstalled using the package manager. Using `apt-get`, the command is: + +```bash +apt-get remove dotnet-host +``` + +Note that there is no version attached to `dotnet-host`. + +If you installed using a tarball, you must remove .NET Core using the manual method. + +You remove the SDKs and runtimes separately, by removing the directory that contains that version. For example, to remove the 1.0.1 SDK and runtime, you would use the following bash commands: + +```bash +sudo rm -rf /usr/share/dotnet/sdk/1.0.1 +sudo rm -rf /usr/share/dotnet/shared/Microsoft.NETCore.App/1.0.1 +sudo rm -rf /usr/share/dotnet/shared/Microsoft.AspNetCore.App/1.0.1 +sudo rm -rf /usr/share/dotnet/host/fxr/1.0.1 +``` + +The parent directories for the SDK and runtime are listed in the output from the `dotnet --list-sdks` and `dotnet --list-runtimes` command, as shown in the earlier table. + +# [macOS](#tab/macOS) + +On Mac, you must remove the SDKs and runtimes separately, by removing the directory that contains that version. For example, to remove the 1.0.1 SDK and runtime, you would use the following bash commands: + +```bash +sudo rm -rf /usr/local/share/dotnet/sdk/1.0.1 +sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.NETCore.App/1.0.1 +sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.AspNetCore.App/1.0.1 +sudo rm -rf /usr/local/share/dotnet/host/fxr/1.0.1 +``` + +The parent directories for the SDK and runtime are listed in the output from the `dotnet --list-sdks` and `dotnet --list-runtimes` command, as shown in the earlier table. + +Starting with .NET Core 2.1, there is no need to uninstall the .NET Core SDK when upgrading it using a package manager. The package manager `update` or `refresh` commands will automatically remove the older version upon the successful installation of a newer version. + +--- diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 323b175692dee..ff372c792f9bf 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -9,7 +9,7 @@ ms.date: 06/27/2018 [!INCLUDE [topic-appliesto-net-core-2plus](../../../includes/topic-appliesto-net-core-2plus.md)] -This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end user machines. These policies perform the following: +This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. These policies perform the following actions: - Easy and efficient deployment of .NET Core, including security and reliability updates. - Use the latest tools and commands independent of target runtime. @@ -25,11 +25,11 @@ The rest of this document examines those four scenarios. ## The SDK uses the latest installed version -SDK commands include `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` CLI must choose an SDK version for any command. The .NET Core CLI uses the latest SDK installed on the machine by default. You'll use the .NET Core SDK v2.1.301 when it's installed, even if the project you are working with targets the .NET Core Runtime 2.0. Note that this is true for preview versions as well as released versions. You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects. +SDK commands include `dotnet new`, , or `dotnet run`. The `dotnet` CLI must choose an SDK version for any command. The .NET Core CLI uses the latest SDK installed on the machine by default. You'll use the .NET Core SDK v2.1.301 when it's installed, even if the project you are working with targets the .NET Core Runtime 2.0. You will use the latest preview versions as well as released versions. You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects. On rare occasions, you may need to use an earlier version of the SDK. You specify that version in a [*global.json* file](../tools/global-json.md). The "use latest" policy means you only use *global.json* to specify a .NET Core SDK version earlier than the latest installed version. -*global.json* can be placed anywhere in the file hierarchy. The CLI searches upward from the project directory for the first *global.json* it finds. You control which projects a given *global.json* applies to by its place in the file system. The .NET CLI searches for a *global.json* file iteratively navigating the path upward from the current working directory. The first *global.json* file found specifies the version used. If that version is installed, that version is used. If the SDK specified in the *global.json* is not found, the .NET CLI rolls forward to the latest SDK installed. This is the same as the default behavior, when no *global.json* file is found. +*global.json* can be placed anywhere in the file hierarchy. The CLI searches upward from the project directory for the first *global.json* it finds. You control which projects a given *global.json* applies to by its place in the file system. The .NET CLI searches for a *global.json* file iteratively navigating the path upward from the current working directory. The first *global.json* file found specifies the version used. If that version is installed, that version is used. If the SDK specified in the *global.json* is not found, the .NET CLI rolls forward to the latest SDK installed. Roll-forward is the same as the default behavior, when no *global.json* file is found. The following example shows the *global.json* syntax: @@ -47,7 +47,7 @@ The process for selecting an SDK version is: 1. `dotnet` uses the SDK specified in the first *global.json* found. 1. `dotnet` uses the latest installed SDK if no *global.json* is found. -You can learn more about selecting an SDK version in the [Matching rules](../tools/global-json.md#matching-rules) section of the topic on *global.json*. +You can learn more about selecting an SDK version in the [Matching rules](../tools/global-json.md#matching-rules) section of the article on *global.json*. ## Target Framework Monikers define build time APIs @@ -103,4 +103,4 @@ Self-contained deployments may require a specific patch version. You can overrid 2.0.4 ``` -The `RuntimeFrameworkVersion` element overrides the default version policy. For self-contained deployments, the `RuntimeFrameworkVersion` specifies the *exact* runtime framework version. For framework dependent applications, the `RuntimeFrameworkVersion` specifies the *minimum* required runtime framework version. +The `RuntimeFrameworkVersion` element overrides the default version policy. For self-contained deployments, the `RuntimeFrameworkVersion` specifies the *exact* runtime framework version. For framework-dependent applications, the `RuntimeFrameworkVersion` specifies the *minimum* required runtime framework version. diff --git a/docs/core/versions/version-history.md b/docs/core/versions/version-history.md new file mode 100644 index 0000000000000..7c2c8a110d705 --- /dev/null +++ b/docs/core/versions/version-history.md @@ -0,0 +1,21 @@ +--- +title: .NET Core version history +description: See the timeline for versions of the .NET Core runtime, .NET Core SDK, C# compiler and VB.NET compiler. +ms.date: 07/26/2018 +--- + +# NET Core version history + +Version numbers for .NET Core are challenging because .NET Core SDK and .NET Core Runtime release on different cadences. The different cadences mean the team was forced to do only two of the following three things: + +1. Release independently, specifically allowing tools, C# and VB to advance faster than the .NET Core Runtime. +2. Maintain alignment in version numbers between .NET Core SDK and .NET Core Runtime. +3. Use semantic versioning for both the .NET Core SDK and .NET Core Runtime. + +2.0.0 forced version alignment and proceeded smoothly for one release. In December 2017 .NET Core SDK had a feature release, with no corresponding release in the .NET Core Runtime. The team chose goals 1 and 3, losing alignment between the .NET Core Runtime and SDK. Several .NET Core SDK 2.1.x versions were released before .NET Core Runtime 2.1. Since the SDK is not forwards compatible, these 2.1.x SDK versions could not target .NET Core Runtime 2.1. The team responded to the considerable confusion by switching to goals 1 and 2, abandoning semantic versioning as described in [.NET Core versioning](index.md#versioning-details). + +Because of the timing of the decision to abandon semantic versioning, there were transitional releases in the 2.1.10x and 2.1.20x version number ranges that also can't target .NET Core Runtime 2.1. + +The first two digits of the version numbers realign with the 2.1.0 version of the .NET Core Runtime and the 2.1.300 version of the .NET Core SDK. + +Detailed information about the versions of individual components, including framework and language compiler versions, can be found on the [.NET Core downloads page](https://www.microsoft.com/net/download/dotnet-core/current). For detailed information about previous versions, select the requested version from the [.NET Core download archives page](https://www.microsoft.com/net/download/archives). Detailed support information can be found in the article describing the official [.NET Support Policy](https://www.microsoft.com/net/Support/Policy). \ No newline at end of file diff --git a/docs/toc.md b/docs/toc.md index f8b2b9a08aadd..b16f80483eebb 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -121,7 +121,9 @@ ### [Unit Testing Published Output](core/testing/unit-testing-published-output.md) ### [Live unit testing .NET Core projects with Visual Studio](/visualstudio/test/live-unit-testing-start) ## [Versioning](core/versions/index.md) +### [.NET Core version history](core/versions/version-history.md) ### [.NET Core version selection](core/versions/selection.md) +### [Removing outdated runtimes and SDKs](core/versions/remove-runtime-sdk-versions.md) ## [Runtime IDentifier catalog](core/rid-catalog.md) ## [.NET Core SDK Overview](core/sdk.md) ## [.NET Core CLI Tools](core/tools/index.md) diff --git a/includes/net-standard-table.md b/includes/net-standard-table.md index f147ba5ece439..d05316daad6b8 100644 --- a/includes/net-standard-table.md +++ b/includes/net-standard-table.md @@ -11,7 +11,7 @@ | Windows Phone | 8.1 | 8.1 | 8.1 | | | | | | | Windows Phone Silverlight | 8.0 | | | | | | | | -1 The versions listed for .NET Framework apply to .NET Core SDK 2.0 and later versions of the tooling. Older versions used a different mapping for .NET Standard 1.5 and higher. +1 The versions listed for .NET Framework apply to .NET Core SDK 2.0 and later versions of the tooling. Older versions used a different mapping for .NET Standard 1.5 and higher. You can [download tooling for .NET Core tools for Visual Studio 2015](https://github.com/dotnet/core/blob/master/release-notes/download-archive.md) if you cannot upgrade to Visual Studio 2017. - The columns represent .NET Standard versions. Each header cell is a link to a document that shows which APIs got added in that version of .NET Standard. - The rows represent the different .NET implementations.