From 794f2a6fc39fe81f9d7da9f31dc1188dbbbf5b1d Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Thu, 8 Jul 2021 10:05:55 -0700 Subject: [PATCH 1/5] Update for version info --- docs/core/project-sdk/msbuild-props.md | 39 +++++++- docs/core/versions/index.md | 71 +++++++------- docs/core/versions/selection.md | 126 +++++++++++++++++++------ 3 files changed, 167 insertions(+), 69 deletions(-) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index ef4f1402a2aa7..992c08fd7182c 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -253,6 +253,8 @@ The following MSBuild properties are documented in this section: - [IsPublishable](#ispublishable) - [PreserveCompilationContext](#preservecompilationcontext) - [PreserveCompilationReferences](#preservecompilationreferences) +- [RollForward](#rollforward) +- [RuntimeFrameworkVersion](#runtimeframeworkversion) - [RuntimeIdentifier](#runtimeidentifier) - [RuntimeIdentifiers](#runtimeidentifiers) - [UseAppHost](#useapphost) @@ -330,6 +332,41 @@ The `PreserveCompilationReferences` property is similar to the [PreserveCompilat For more information, see [Razor SDK properties](/aspnet/core/razor-pages/sdk#properties). +### RollForward + +The `RollForward` property controls the how the application chooses a different runtime when the targetted runtime is unavailable. This value is output to the *.runtimeconfig.json* as the `rollForward` setting. + +```xml + + LatestMinor + +``` + +Set `RollForward` to one of the following values: + +| Value | Description | +|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `LatestPatch` | Roll-forward to the highest patch version. This value disables minor version roll-forward. | +| `Minor` | Roll-forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the `LatestPatch` policy is used. | +| `Major` | Roll-forward to the next available higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the `Minor` policy is used. | +| `LatestMinor` | Roll-forward to highest minor version, even if requested minor version is present. | +| `LatestMajor` | Roll-forward to highest major and highest minor version, even if requested major is present. | +| `Disable` | Don't roll-forward, only bind to the specified version. This policy isn't recommended for general use since it disables the ability to roll-forward to the latest patches. This value is only recommended for testing. | + +For more information, see [Control roll-forward behavior](../versions/selection.md#control-roll-forward-behavior). + +### RuntimeFrameworkVersion + +The `RuntimeFrameworkVersion` property specifies the version of the runtime to use when publishing. Specify a runtime version: + +``` xml + + 5.0.7 + +``` + +When publishing a framework-dependent application, this value specifies the minimum version required. When publishing a self-contained application, this value specifies the *exact* version required. + ### RuntimeIdentifier The `RuntimeIdentifier` property lets you specify a single [runtime identifier (RID)](../rid-catalog.md) for the project. The RID enables publishing a self-contained deployment. @@ -783,7 +820,7 @@ For more information, see [Expose .NET components to COM](../native-interop/expo The `EnableDynamicLoading` property indicates that an assembly is a dynamically loaded component. The component could be a [COM library](/windows/win32/com/the-component-object-model) or a non-COM library that can be [used from a native host](../tutorials/netcore-hosting.md). Setting this property to `true` has the following effects: - A *.runtimeconfig.json* file is generated. -- [Roll forward](../whats-new/dotnet-core-3-0.md#major-version-runtime-roll-forward) is set to `LatestMinor`. +- [RollForward](#rollforward) is set to `LatestMinor`. - NuGet references are copied locally. ```xml diff --git a/docs/core/versions/index.md b/docs/core/versions/index.md index 728a728947af8..314037f0190d1 100644 --- a/docs/core/versions/index.md +++ b/docs/core/versions/index.md @@ -1,33 +1,35 @@ --- title: How the .NET Runtime and SDK are versioned description: This article explains how the .NET SDK and Runtime are versioned (similar to semantic versioning). -ms.date: 12/07/2020 +ms.date: 07/08/2021 --- # Overview of how .NET is versioned The [.NET Runtime and the .NET SDK](../introduction.md#sdk-and-runtimes) add new features at different frequencies. In general, the SDK is updated more frequently than the Runtime. This article explains the runtime and the SDK version numbers. +.NET releases a new major version every November. Even-numbered releases, such as .NET 6 or .NET 8, are long-term supported (LTS). Odd-numbered releases are supported until the next major release. The latest release of .NET is .NET 5. + ## Versioning details -The .NET Runtime has a major/minor/patch approach to versioning that follows [semantic versioning](#semantic-versioning). +The .NET Runtime has a major.minor.patch approach to versioning that follows [semantic versioning](#semantic-versioning). -The .NET SDK doesn't follow semantic versioning. The .NET SDK releases faster and its version numbers must communicate both the aligned runtime and the SDK's own minor and patch releases. +The .NET SDK, however, doesn't follow semantic versioning. The .NET SDK releases faster and its version numbers must communicate both the aligned runtime and the SDK's own minor and patch releases. -The first two positions of the .NET SDK version number are locked to the .NET Runtime version it released with. Each version of the SDK can create applications for this runtime or any lower version. +The first two positions of the .NET SDK version number match the .NET Runtime version it released with. Each version of the SDK can create applications for this runtime or any lower version. The third position of the SDK version number communicates both the minor and patch number. The minor version is multiplied by 100. The final two digits represent the patch number. Minor version 1, patch version 2 would be represented as 102. For example, here's a possible sequence of runtime and SDK version numbers: | Change | .NET Runtime | .NET 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 | +| Initial release | 5.0.0 | 5.0.100 | +| SDK patch | 5.0.0 | 5.0.101 | +| Runtime and SDK patch | 5.0.1 | 5.0.102 | +| SDK feature change | 5.0.1 | 5.0.200 | NOTES: -- 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. +- If the SDK has 10 feature updates before a runtime feature update, version numbers roll into the 1000 series. Version 5.0.1000 would follow version 5.0.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. You can see more details in the initial proposal at the [dotnet/designs](https://github.com/dotnet/designs/pull/29) repository. @@ -44,50 +46,41 @@ The optional `PRERELEASE` and `BUILDNUMBER` parts are never part of supported re ### Understand runtime version number changes -`MAJOR` is incremented when: - -- 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. +- `MAJOR` is incremented once a year and may contain: -`MINOR` is incremented when: + - Significant changes in the product, or a new product direction. + - API introduced breaking changes. There's a high bar to accepting breaking changes. + - A newer `MAJOR` version of an existing dependency is adopted. + + Major releases happen once a year, even-numbered versions are long-term supported (LTS) releases. The first LTS release using this versioning scheme is .NET 6, which will be released in November 2021. The latest non-LTS version is .NET 5. + +- `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: +- `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. +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.PATCH` are reset to zero. When `MINOR` is incremented, `PATCH` is reset to zero while `MAJOR` remains the same. ## Version numbers in file names -The files downloaded for .NET carry the version, for example, `dotnet-sdk-2.1.300-win10-x64.exe`. +The files downloaded for .NET carry the version, for example, `dotnet-sdk-5.0.301-win10-x64.exe`. ### Preview versions -Preview versions have a `-preview[number]-([build]|"final")` appended to the version number. For example, `2.0.0-preview1-final`. +Preview versions have a `-preview.[number].[build]` appended to the version number. For example, `6.0.0-preview.5.21302.13`. ### Servicing versions -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`. - -## Relationship to .NET Standard versions - -.NET Standard consists of a .NET reference assembly. There are multiple implementations specific to each platform. The reference assembly contains the definition of .NET APIs which are part of a given .NET Standard version. Each implementation fulfills the .NET Standard contract on the specific platform. - -The .NET Standard reference assembly uses a `MAJOR.MINOR` versioning scheme. `PATCH` level isn't useful for .NET Standard because it exposes only an API specification (no implementation) and by definition any change to the API would represent a change in the feature set, and thus a new `MINOR` version. - -The implementations on each platform may be updated, typically as part of the platform release, and thus not evident to the programmers using .NET Standard on that platform. - -For more information, see [.NET Standard](../../standard/net-standard.md). +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, `5.0.1-servicing-006924`. ## See also diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index b767e48b2e509..5b86af7657b68 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -3,12 +3,12 @@ title: Select which .NET version to use description: Learn how .NET automatically finds and chooses runtime versions for your program. Additionally, this article teaches you how to force a specific version. author: adegeo ms.author: adegeo -ms.date: 02/05/2021 +ms.date: 07/08/2021 --- # Select the .NET version to use -This article explains the policies used by the .NET 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: +This article explains the policies used by the .NET 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 enable: - Easy and efficient deployment of .NET, including security and reliability updates. - Use the latest tools and commands independent of target runtime. @@ -17,7 +17,7 @@ Version selection occurs: - When you run an SDK command, [the SDK uses the latest installed version](#the-sdk-uses-the-latest-installed-version). - When you build an assembly, [target framework monikers define build time APIs](#target-framework-monikers-define-build-time-apis). -- When you run a .NET application, [target framework dependent apps roll forward](#framework-dependent-apps-roll-forward). +- When you run a .NET application, [target framework dependent apps roll-forward](#framework-dependent-apps-roll-forward). - When you publish a self-contained application, [self-contained deployments include the selected runtime](#self-contained-deployments-include-the-selected-runtime). The rest of this document examines those four scenarios. @@ -29,83 +29,151 @@ SDK commands include `dotnet new` and `dotnet run`. The .NET CLI must choose an - The project targets an earlier version of the .NET runtime. - The latest version of the .NET SDK is a preview version. -You can take advantage of the latest SDK features and improvements while targeting earlier .NET runtime versions. You can target multiple runtime versions of .NET on different projects, using the same SDK tools for all projects. +You can take advantage of the latest SDK features and improvements while targeting earlier .NET runtime versions. You can target different runtime versions of .NET using the same SDK tools. 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 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 SDK version is installed, that version is used. If the SDK specified in the *global.json* is not found, the .NET CLI uses [matching rules](../tools/global-json.md#matching-rules) to select a compatible SDK, or fails if none 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 SDK version is installed, that version is used. If the SDK specified in the *global.json* isn't found, the .NET CLI uses [matching rules](../tools/global-json.md#matching-rules) to select a compatible SDK, or fails if none is found. The following example shows the *global.json* syntax: ``` json { "sdk": { - "version": "3.0.0" + "version": "5.0.0" } } ``` The process for selecting an SDK version is: -1. `dotnet` searches for a *global.json* file iteratively reverse-navigating the path upward from the current working directory. -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. +01. `dotnet` searches for a *global.json* file iteratively reverse-navigating the path upward from the current working directory. +01. `dotnet` uses the SDK specified in the first *global.json* found. +01. `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 article on *global.json*. +For more information about SDK version selection, seethe [Matching rules](../tools/global-json.md#matching-rules) and [rollForward](../tools/global-json.md#rollforward) sections of the [global.json overview](../tools/global-json.md) article. ## Target Framework Monikers define build time APIs You build your project against APIs defined in a **Target Framework Moniker** (TFM). You specify the [target framework](../../standard/frameworks.md) in the project file. Set the `TargetFramework` element in your project file as shown in the following example: ``` xml -netcoreapp3.0 +net5.0 ``` You may build your project against multiple TFMs. Setting multiple target frameworks is more common for libraries but can be done with applications as well. You specify a `TargetFrameworks` property (plural of `TargetFramework`). The target frameworks are semicolon-delimited as shown in the following example: ``` xml -netcoreapp3.0;net47 +net5.0;netcoreapp3.1;net47 ``` -A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. For example, the .NET Core 3.1 SDK includes the .NET Core 3.1 runtime, which is an implementation of the `netcoreapp3.0` target framework. The .NET Core 3.1 SDK supports `netcoreapp2.1`, `netcoreapp2.2`, `netcoreapp3.0`, but not `net5.0` (or higher). You install the .NET 5.0 SDK to build for `net5.0`. +A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. For example, the .NET 5.0 SDK includes the .NET 5.0 runtime, which is an implementation of the `net5.0` target framework. The .NET 5.0 SDK supports `netcoreapp2.0`, `netcoreapp2.1`, `netcoreapp3.0`, and so on, but not `net6.0` (or higher). You install the .NET 6.0 SDK to build for `net6.0`. -.NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. The .NET 5.0 SDK is capped to `netstandard2.1`. For more information, see [.NET Standard](../../standard/net-standard.md). +### .NET Standard -## Framework-dependent apps roll forward +.NET Standard was a way to target an API surface shared by different implementations of .NET. Starting with the release of .NET 5, which is an API standard itself, .NET Standard has little relevance, except for one scenario: .NET Standard is useful when you want to target both .NET and .NET Framework. .NET 5 implements all .NET Standard versions. + +For more information, see [.NET 5 and .NET Standard](../../standard/net-standard.md#net-5-and-net-standard). + +## Framework-dependent apps roll-forward When you run an application from source with [`dotnet run`](../tools/dotnet-run.md), from a [**framework-dependent deployment**](../deploying/index.md#publish-framework-dependent) with [`dotnet myapp.dll`](../tools/dotnet.md#description), or from a [**framework-dependent executable**](../deploying/index.md#publish-framework-dependent) with `myapp.exe`, the `dotnet` executable is the **host** for the application. -The host chooses the latest patch version installed on the machine. For example, if you specified `netcoreapp3.0` in your project file, and `3.0.2` is the latest .NET runtime installed, the `3.0.2` runtime is used. +The host chooses the latest patch version installed on the machine. For example, if you specified `net5.0` in your project file, and `5.0.2` is the latest .NET runtime installed, the `5.0.2` runtime is used. -If no acceptable `3.0.*` version is found, a new `3.*` version is used. For example, if you specified `netcoreapp3.0` and only `3.1.0` is installed, the application runs using the `3.1.0` runtime. This behavior is referred to as "minor version roll-forward." Lower versions also won't be considered. When no acceptable runtime is installed, the application won't run. +If no acceptable `5.0.*` version is found, a new `5.*` version is used. For example, if you specified `net5.0` and only `5.1.0` is installed, the application runs using the `5.1.0` runtime. This behavior is referred to as "minor version roll-forward." Lower versions also won't be considered. When no acceptable runtime is installed, the application won't run. -A few usage examples demonstrate the behavior, if you target 3.0: +A few usage examples demonstrate the behavior, if you target 5.0: -- ✔️ 3.0 is specified. 3.0.3 is the highest patch version installed. 3.0.3 is used. -- ❌ 3.0 is specified. No 3.0.* versions are installed. 2.1.1 is the highest runtime installed. An error message is displayed. -- ✔️ 3.0 is specified. No 3.0.* versions are installed. 3.1.0 is the highest runtime version installed. 3.1.0 is used. -- ❌ 2.0 is specified. No 2.x versions are installed. 3.0.0 is the highest runtime installed. An error message is displayed. +- ✔️ 5.0 is specified. 5.0.3 is the highest patch version installed. 5.0.3 is used. +- ❌ 5.0 is specified. No 5.0.* versions are installed. 3.1.1 is the highest runtime installed. An error message is displayed. +- ✔️ 5.0 is specified. No 5.0.* versions are installed. 5.1.0 is the highest runtime version installed. 5.1.0 is used. +- ❌ 3.0 is specified. No 3.x versions are installed. 5.0.0 is the highest runtime installed. An error message is displayed. Minor version roll-forward has one side-effect that may affect end users. Consider the following scenario: -1. The application specifies that 3.0 is required. -2. When run, version 3.0.* is not installed, however, 3.1.0 is. Version 3.1.0 will be used. -3. Later, the user installs 3.0.3 and runs the application again, 3.0.3 will now be used. +01. The application specifies that 5.0 is required. +02. When run, version 5.0.* isn't installed, however, 5.1.0 is. Version 3.1.0 will be used. +03. Later, the user installs 5.0.3 and runs the application again, 5.0.3 will now be used. + +It's possible that 5.0.3 and 5.1.0 behave differently, particularly for scenarios like serializing binary data. + +### Control roll-forward behavior + +The roll-forward behavior for an app or for .NET, can be configured in four different ways: + +01. Project-level setting by setting the `` property: + + ```xml + + LatestMinor + + ``` + +02. The `*.runtimeconfig.json` file. + + This file is produced when you compile your app. If the `` property was set in the project, it's reproduced in the `*.runtimeconfig.json` file as the `rollForward` setting. Users can edit this file to change the behavior of your app. + + ```json + { + "runtimeOptions": { + "tfm": "net5.0", + "rollForward": "LatestMinor", + "framework": { + "name": "Microsoft.NETCore.App", + "version": "5.0.0" + } + } + } + ``` + +03. The `dotnet` command's `--roll-forward ` property. + + When you run an app, you can control the roll-forward behavior through the command line: + + ```dotnet + dotnet run --roll-forward LatestMinor + dotnet myapp.dll --roll-forward LatestMinor + myapp.exe --roll-forward LatestMinor + ``` + +04. The `DOTNET_ROLL_FORWARD` environment setting. + +### Precedence + +Roll forward behavior is considered in the following order: + +01. `*.runtimeconfig.json` config file. +01. The `DOTNET_ROLL_FORWARD` environment setting. +01. Any `--roll-forward` parameter passed to the running app. + +### Values + +However you set the roll-forward setting, use one of the following values to set the behavior: -It's possible that 3.0.3 and 3.1.0 behave differently, particularly for scenarios like serializing binary data. +| Value | Description | +|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `LatestPatch` | Roll-forward to the highest patch version. This value disables minor version roll-forward. | +| `Minor` | Roll-forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the `LatestPatch` policy is used. | +| `Major` | Roll-forward to the next available higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the `Minor` policy is used. | +| `LatestMinor` | Roll-forward to highest minor version, even if requested minor version is present. | +| `LatestMajor` | Roll-forward to highest major and highest minor version, even if requested major is present. | +| `Disable` | Don't roll-forward, only bind to the specified version. This policy isn't recommended for general use since it disables the ability to roll-forward to the latest patches. This value is only recommended for testing. | ## Self-contained deployments include the selected runtime You can publish an application as a [**self-contained distribution**](../deploying/index.md#publish-self-contained). This approach bundles the .NET runtime and libraries with your application. Self-contained deployments don't have a dependency on runtime environments. Runtime version selection occurs at publishing time, not run time. -The publishing process selects the latest patch version of the given runtime family. For example, `dotnet publish` will select .NET Core 3.0.3 if it is the latest patch version in the .NET Core 3.0 runtime family. The target framework (including the latest installed security patches) is packaged with the application. +The *restore* event that occurs when publishing selects the latest patch version of the given runtime family. For example, `dotnet publish` will select .NET 5.0.3 if it's the latest patch version in the .NET 5.0 runtime family. The target framework (including the latest installed security patches) is packaged with the application. -It's an error if the minimum version specified for an application isn't satisfied. `dotnet publish` binds to the latest runtime patch version (within a given major.minor version family). `dotnet publish` doesn't support the roll-forward semantics of `dotnet run`. For more information about patches and self-contained deployments, see the article on [runtime patch selection](../deploying/runtime-patch-selection.md) in deploying .NET applications. +An error occurs if the minimum version specified for an application isn't satisfied. `dotnet publish` binds to the latest runtime patch version (within a given major.minor version family). `dotnet publish` doesn't support the roll-forward semantics of `dotnet run`. For more information about patches and self-contained deployments, see the article on [runtime patch selection](../deploying/runtime-patch-selection.md) in deploying .NET applications. Self-contained deployments may require a specific patch version. You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example: ``` xml -3.0.3 + + 5.0.7 + ``` 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. From 37ba639e10bd5a50fe61608558838d91abd24f6a Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Thu, 8 Jul 2021 10:15:57 -0700 Subject: [PATCH 2/5] standardize on application for article --- docs/core/versions/selection.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 5b86af7657b68..ebc68190751f3 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -100,7 +100,7 @@ It's possible that 5.0.3 and 5.1.0 behave differently, particularly for scenario ### Control roll-forward behavior -The roll-forward behavior for an app or for .NET, can be configured in four different ways: +The roll-forward behavior for an application, can be configured in four different ways: 01. Project-level setting by setting the `` property: @@ -112,7 +112,7 @@ The roll-forward behavior for an app or for .NET, can be configured in four diff 02. The `*.runtimeconfig.json` file. - This file is produced when you compile your app. If the `` property was set in the project, it's reproduced in the `*.runtimeconfig.json` file as the `rollForward` setting. Users can edit this file to change the behavior of your app. + This file is produced when you compile your application. If the `` property was set in the project, it's reproduced in the `*.runtimeconfig.json` file as the `rollForward` setting. Users can edit this file to change the behavior of your application. ```json { @@ -129,7 +129,7 @@ The roll-forward behavior for an app or for .NET, can be configured in four diff 03. The `dotnet` command's `--roll-forward ` property. - When you run an app, you can control the roll-forward behavior through the command line: + When you run an application, you can control the roll-forward behavior through the command line: ```dotnet dotnet run --roll-forward LatestMinor @@ -145,7 +145,7 @@ Roll forward behavior is considered in the following order: 01. `*.runtimeconfig.json` config file. 01. The `DOTNET_ROLL_FORWARD` environment setting. -01. Any `--roll-forward` parameter passed to the running app. +01. Any `--roll-forward` parameter passed to the running application. ### Values From 161f566a4910c6719206456eb427cebc29aeb28b Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Thu, 8 Jul 2021 12:01:48 -0700 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Vitek Karas Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/project-sdk/msbuild-props.md | 6 +++--- docs/core/versions/selection.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index 992c08fd7182c..de06f7148b5aa 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -334,7 +334,7 @@ For more information, see [Razor SDK properties](/aspnet/core/razor-pages/sdk#pr ### RollForward -The `RollForward` property controls the how the application chooses a different runtime when the targetted runtime is unavailable. This value is output to the *.runtimeconfig.json* as the `rollForward` setting. +The `RollForward` property controls how the application chooses a runtime when multiple runtime versions are available. This value is output to the *.runtimeconfig.json* as the `rollForward` setting. ```xml @@ -347,7 +347,7 @@ Set `RollForward` to one of the following values: | Value | Description | |---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `LatestPatch` | Roll-forward to the highest patch version. This value disables minor version roll-forward. | -| `Minor` | Roll-forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the `LatestPatch` policy is used. | +| `Minor` | **Default** Roll-forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the `LatestPatch` policy is used. | | `Major` | Roll-forward to the next available higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the `Minor` policy is used. | | `LatestMinor` | Roll-forward to highest minor version, even if requested minor version is present. | | `LatestMajor` | Roll-forward to highest major and highest minor version, even if requested major is present. | @@ -365,7 +365,7 @@ The `RuntimeFrameworkVersion` property specifies the version of the runtime to u ``` -When publishing a framework-dependent application, this value specifies the minimum version required. When publishing a self-contained application, this value specifies the *exact* version required. +When publishing a framework-dependent application, this value specifies the *minimum* version required. When publishing a self-contained application, this value specifies the *exact* version required. ### RuntimeIdentifier diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index ebc68190751f3..0ebc6bc890c37 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -51,7 +51,7 @@ The process for selecting an SDK version is: 01. `dotnet` uses the SDK specified in the first *global.json* found. 01. `dotnet` uses the latest installed SDK if no *global.json* is found. -For more information about SDK version selection, seethe [Matching rules](../tools/global-json.md#matching-rules) and [rollForward](../tools/global-json.md#rollforward) sections of the [global.json overview](../tools/global-json.md) article. +For more information about SDK version selection, see the [Matching rules](../tools/global-json.md#matching-rules) and [rollForward](../tools/global-json.md#rollforward) sections of the [global.json overview](../tools/global-json.md) article. ## Target Framework Monikers define build time APIs @@ -100,7 +100,7 @@ It's possible that 5.0.3 and 5.1.0 behave differently, particularly for scenario ### Control roll-forward behavior -The roll-forward behavior for an application, can be configured in four different ways: +The roll-forward behavior for an application can be configured in four different ways: 01. Project-level setting by setting the `` property: @@ -144,7 +144,7 @@ The roll-forward behavior for an application, can be configured in four differen Roll forward behavior is considered in the following order: 01. `*.runtimeconfig.json` config file. -01. The `DOTNET_ROLL_FORWARD` environment setting. +01. The `DOTNET_ROLL_FORWARD` environment variable. 01. Any `--roll-forward` parameter passed to the running application. ### Values From 998d2a481c6887270379c1d4afcc90eaa10568d0 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Thu, 8 Jul 2021 12:09:46 -0700 Subject: [PATCH 4/5] feedback --- docs/core/project-sdk/msbuild-props.md | 9 +-------- docs/core/versions/selection.md | 9 +-------- includes/roll-forward-table.md | 16 ++++++++++++++++ 3 files changed, 18 insertions(+), 16 deletions(-) create mode 100644 includes/roll-forward-table.md diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index de06f7148b5aa..1f17634c82abf 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -344,14 +344,7 @@ The `RollForward` property controls how the application chooses a runtime when m Set `RollForward` to one of the following values: -| Value | Description | -|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `LatestPatch` | Roll-forward to the highest patch version. This value disables minor version roll-forward. | -| `Minor` | **Default** Roll-forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the `LatestPatch` policy is used. | -| `Major` | Roll-forward to the next available higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the `Minor` policy is used. | -| `LatestMinor` | Roll-forward to highest minor version, even if requested minor version is present. | -| `LatestMajor` | Roll-forward to highest major and highest minor version, even if requested major is present. | -| `Disable` | Don't roll-forward, only bind to the specified version. This policy isn't recommended for general use since it disables the ability to roll-forward to the latest patches. This value is only recommended for testing. | +[!INCLUDE [roll-forward-table](../../../includes/roll-forward-table.md)] For more information, see [Control roll-forward behavior](../versions/selection.md#control-roll-forward-behavior). diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 0ebc6bc890c37..64c42a2bee6c5 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -151,14 +151,7 @@ Roll forward behavior is considered in the following order: However you set the roll-forward setting, use one of the following values to set the behavior: -| Value | Description | -|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `LatestPatch` | Roll-forward to the highest patch version. This value disables minor version roll-forward. | -| `Minor` | Roll-forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the `LatestPatch` policy is used. | -| `Major` | Roll-forward to the next available higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the `Minor` policy is used. | -| `LatestMinor` | Roll-forward to highest minor version, even if requested minor version is present. | -| `LatestMajor` | Roll-forward to highest major and highest minor version, even if requested major is present. | -| `Disable` | Don't roll-forward, only bind to the specified version. This policy isn't recommended for general use since it disables the ability to roll-forward to the latest patches. This value is only recommended for testing. | +[!INCLUDE [roll-forward-table](../../../includes/roll-forward-table.md)] ## Self-contained deployments include the selected runtime diff --git a/includes/roll-forward-table.md b/includes/roll-forward-table.md new file mode 100644 index 0000000000000..4f0964d092c08 --- /dev/null +++ b/includes/roll-forward-table.md @@ -0,0 +1,16 @@ +--- +author: adegeo +ms.author: adegeo +ms.date: 07/08/2021 +ms.topic: include +recommendations: false +--- + +| Value | Description | +|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Minor` | **Default** if not specified.
Roll-forward to the lowest higher minor version, if requested minor version is missing. If the requested minor version is present, then the `LatestPatch` policy is used. | +| `Major` | Roll-forward to the next available higher major version, and lowest minor version, if requested major version is missing. If the requested major version is present, then the `Minor` policy is used. | +| `LatestPatch` | Roll-forward to the highest patch version. This value disables minor version roll-forward. | +| `LatestMinor` | Roll-forward to highest minor version, even if requested minor version is present. | +| `LatestMajor` | Roll-forward to highest major and highest minor version, even if requested major is present. | +| `Disable` | Don't roll-forward, only bind to the specified version. This policy isn't recommended for general use since it disables the ability to roll-forward to the latest patches. This value is only recommended for testing. | From faa4290e131516f550b063c797f7d8893bc63145 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Thu, 8 Jul 2021 12:24:47 -0700 Subject: [PATCH 5/5] Update docs/core/versions/selection.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/versions/selection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 64c42a2bee6c5..84a6a8fd4c154 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -137,7 +137,7 @@ The roll-forward behavior for an application can be configured in four different myapp.exe --roll-forward LatestMinor ``` -04. The `DOTNET_ROLL_FORWARD` environment setting. +04. The `DOTNET_ROLL_FORWARD` environment variable. ### Precedence