Document .Net core version binding #6060
Conversation
There was a problem hiding this comment.
Thanks for working on this @BillWagner! Got halfway through this so far. Left some comments.
docs/core/versions/binding.md
Outdated
| @@ -0,0 +1,170 @@ | |||
| --- | |||
| title: .NET Core 2 and later version binding | |||
| description: Learn How the .NET runtime finds and chooses versions during build and run for your program | |||
There was a problem hiding this comment.
I'm not crazy about conflating the runtime and SDK selection. They happen at quite different times in the user's flow. Could we have subsections that nearly immediately break to version a runtime and an SDK section? I think a few places here are unnecessarily complicated because of this combination.
There was a problem hiding this comment.
Also, I'd really like to keep a good distinction between .NET Core Runtime and .NET Core SDK in the docs. Phrases like ".NET Core 2.0 development" I think add to the confusion "target multiple versions of .NET Core". Even if the current structure remains, I'd like to see distinction made throughout between .NET Core Runtime and .NET Core SDK. With this distinction, several places will iron out smoothly, like the section on using the newest SDK with any runtime.
If this is a broader strategic/policy discussion, I'd like to be included.
docs/core/versions/binding.md
Outdated
| ms.author: wiwagn | ||
| ms.date: 06/21/2018 | ||
| --- | ||
| # .NET Core 2 and later version binding |
There was a problem hiding this comment.
wouldn't be better to call this .NET Core version binding?
and then add something like the applies to we have in the CLI topics (https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-clean)?
docs/core/versions/binding.md
Outdated
|
|
||
| When needed, you configure `dotnet` to use a different 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 version earlier than the latest installed version. | ||
|
|
||
| `global.json`can be used at different scopes: |
There was a problem hiding this comment.
I think this is better explained by the file system. I don't think the word scope helps much.
globlal.json can appear anywhere in the file hierarchy. If multiple global.json files exist, only the file closest to the project will be used. This allows you to define the SDK for a project, group of projects or all projects.
docs/core/versions/binding.md
Outdated
| <TargetFramework>netcoreapp2.0</TargetFramework> | ||
| ``` | ||
|
|
||
| You set multiple target frameworks if you need to build different code for different environments. 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 will be semicolon-delimited as shown in the following example: |
There was a problem hiding this comment.
nit: remove comma before but
Start with the if clause and remove the you
If you need to build different code for different environments, set ....
also not sure if environment is the right word here.
There was a problem hiding this comment.
Me either. I tried ".net implementations" but that doesn't feel right either.
There was a problem hiding this comment.
Maybe this is a nit, but not all targets are environments. We have both the metapackages and netstandard. Also, I'd leave out the library sentence. It's not really wrong, just irrelevant. Can we just say:
You can set multiple target frameworks. You specify...
docs/core/versions/binding.md
Outdated
| <TargetFrameworks>netcoreapp2.0;net47</TargetFrameworks> | ||
| ``` | ||
|
|
||
| A given SDK will support a fixed set of frameworks, typically capped to the target framework of the runtime(s) it includes. For example, the .NET Core 2.0 SDK includes the .NET Core 2.0 runtime, which is an implementation of the `netcoreapp2.0` target framework. The .NET Core 2.0 SDK will support `netcoreapp1.0`, `netcoreapp1.1`, and `netcoreapp2.0` but not `netcoreapp2.1` (or higher). You'll need to install the .NET Core 2.1 SDK in order to build for `netcoreapp2.1`. |
There was a problem hiding this comment.
runtime(s) -> runtimes? (https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/s-es)
remove future tense? (general comment for the whole topic)
There was a problem hiding this comment.
Future tense: I caught some. Checking again.
There was a problem hiding this comment.
Drop the word typically. It's capped now and forward.
There was a problem hiding this comment.
Did we earlier draw the relationship between a target framework and a runtime?
At what point prior to this did we explain that the SDK contains a runtime? Let's drop them in gently by ending the last sentence (and no plural here that I can think of)
...capped to the target framework of the runtime it ships with. For example...
docs/core/versions/binding.md
Outdated
|
|
||
| ## Select a target SDK | ||
|
|
||
| You specify the target framework in the project file. Set the `TargetFramework` as shown in the following example: |
There was a problem hiding this comment.
Set the TargetFramework element, property? why do you specify the target framework?
do you need to establish the relationship between setting the TFM and the SDK selection? I don't think the heading here in this section is correct
There was a problem hiding this comment.
The heading is wrong, or we should chat ;-)
docs/core/versions/binding.md
Outdated
| <RuntimeFrameworkVersion>2.0.4</RuntimeFrameworkVersion> | ||
| ``` | ||
|
|
||
| When you target multiple target frameworks, you must specify the minimum runtime patch version to the specific .NET Core target framework, as shown in the following example: |
There was a problem hiding this comment.
target multiple target -> target multiple
what happens if you don't specify the mininum runtime patch?
There was a problem hiding this comment.
I didn't know this.
@livarcocc can you confirm?
There was a problem hiding this comment.
@KathleenDollard can you comment? (I honestly don't know).
docs/core/versions/binding.md
Outdated
|
|
||
| ## Minimum required runtime version | ||
|
|
||
| You run an application from source with `dotnet run`. `dotnet run` both builds and runs an application. |
docs/core/versions/binding.md
Outdated
|
|
||
| The built application runs on machines that satisfy the minimum required runtime patch version, stored in the `*.runtimeconfig.json` file. The highest patch version is selected. For example, the `2.0.4` runtime is selected in the case that the minimum runtime version is `2.0.0` while `2.0.0`, `2.0.1` and `2.0.4` are all installed on the machine. Higher minor or major versions (for example, `2.1.1` or `3.0.1`) won't be considered. Lower versions also won't be considered. | ||
|
|
||
| It's an error if the minimum version specified for an application is not satisfied. However, you may run an application on a machine that is missing the runtime required by the application. If a higher minor version is installed, the minor version is used instead of failing. Higher major versions will not be used to load applications. This behavior is referred to as "minor version roll-forward." |
There was a problem hiding this comment.
confusing paragraph
It's an error if the minimum version specified for an application is not satisfied. -> If the minimum version specified for an application is not found at run time, what happens? it seems that the app would fail to run no matter what if the minimum version is not found.
you may run -> you may be able to run
There was a problem hiding this comment.
This paragraph was redundant with the previous paragraph. Combined where applicable, deleted the rest.
docs/core/versions/binding.md
Outdated
| If neither is found, you see an error message similar to the following example: | ||
|
|
||
| > This application requires .NET Core 2.0.4. Please install .NET Core 2.0.4 or a higher compatible version. | ||
| > Please see https://aka.ms/install-dotnet-core to learn about .NET Core installation and runtime versioning. |
There was a problem hiding this comment.
this link goes to microsoft homepage. shouldn't this link be working already?
docs/core/versions/binding.md
Outdated
|
|
||
| ## Publish a self-contained application | ||
|
|
||
| You can publish an application as a **self-contained distribution**. This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. |
There was a problem hiding this comment.
link to https://docs.microsoft.com/en-us/dotnet/core/deploying/#self-contained-deployments-scd for the definition of self-contained and the other anchor framework-dependent apps. Also, do we need to link from that topic back here for learning about version binding at publishing time?
There was a problem hiding this comment.
in second sentence: "includes NET Core runtime."
Drop the third sentence. It is incorrect. The fourth is the point. If you like, move the third to fourth and restate to be very clear you mean it does not depend on a framework that is installed on the machine.
There was a problem hiding this comment.
Overall I think this article takes a simple topic and makes it more complicated than it needs to be.
Also:
- inconsistent use of the words runtime and framework. I think we should make sure we have some clear definitions on that
- use of the word runtime to mean both .NET Core runtime and the running time of an application
- a lack of clarity brought on by the use of .NET Core (which is simply a brand, there is no such actual thing) to refer to the SDK or runtime)
docs/core/versions/binding.md
Outdated
| - Select a runtime to publish an application (with `dotnet publish`). | ||
|
|
||
| The installation structure is machine global and in the path by default. This rule enables a developer to access all .NET Core versions from any command prompt. The structure enables updating all apps to use a new .NET Core patch version by installing it in this central structure/location. You may also use private .NET Core installations without use of the path. | ||
|
|
There was a problem hiding this comment.
I think the second sentence is unclear and should just be dropped. I don't see a rule to be "this rule" for example. We also only give you easy access to the latest SDK (the only thing you can access from the command prompt.
docs/core/versions/binding.md
Outdated
|
|
||
| These policies perform the following roles: | ||
|
|
||
| - Provide an implicit "version manager" experience. |
There was a problem hiding this comment.
I don't really think we provide a version manager experience. I would like to. But now, we just have a sort of hacky way you can control your SDK version, and the runtime is just stated. I like the other bullet points.
docs/core/versions/binding.md
Outdated
| @@ -0,0 +1,170 @@ | |||
| --- | |||
| title: .NET Core 2 and later version binding | |||
| description: Learn How the .NET runtime finds and chooses versions during build and run for your program | |||
There was a problem hiding this comment.
I'm not crazy about conflating the runtime and SDK selection. They happen at quite different times in the user's flow. Could we have subsections that nearly immediately break to version a runtime and an SDK section? I think a few places here are unnecessarily complicated because of this combination.
docs/core/versions/binding.md
Outdated
| There are multiple actions where version binding takes place: | ||
|
|
||
| - Select an [SDK](#select-an-sdk-version). | ||
| - Select a [target framework](#select-a-target-framework) for the application. |
There was a problem hiding this comment.
nit: where the binding takes place I think would collapse the last two. Considerations?
docs/core/versions/binding.md
Outdated
|
|
||
| ## Select an SDK version | ||
|
|
||
| Your first experience with .NET Core is typically with an SDK command, for example `dotnet new`, `dotnet build` or `dotnet run`. The `dotnet` command must use a chosen version of the SDK for these commands. .NET Core uses the latest SDK. You'll use the .NET Core 99.9 SDK when it's installed, even if you're using the SDK command for .NET Core 2.0 development. |
There was a problem hiding this comment.
Yes to both. I think the last sentence could be:
You'll use the .NET Core 99.9 SDK when it's installed, even if the project you are working with targets the .NET Core Runtime 2.0.
docs/core/versions/binding.md
Outdated
| - The application doesn't specify a hosting environment. | ||
| - The developer generates a final configuration for the application (that can't be practically modified). The best runtime choice is the latest installed runtime patch version. It's the same version used for development and it has the latest (per the machine) security and reliability fixes. | ||
|
|
||
| The `runtimeframeworkversion` element will override the default version policy if that element is present in the project file. |
There was a problem hiding this comment.
Please move before intent where the rules are listed.
docs/core/versions/binding.md
Outdated
|
|
||
| The `runtimeframeworkversion` element will override the default version policy if that element is present in the project file. | ||
|
|
||
| It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. |
There was a problem hiding this comment.
Second sentence has already been stated. Third is problematic. It does support patch roll-forward, as already discussed. The rules are different, which if it's going to be stated should probably be in the first paragraph of the self-contained section.
@dsplaisted can you confirm that at publish there is not runtime minor roll-forward?
docs/core/versions/binding.md
Outdated
| You publish with the latest runtime patch version for the given target framework specifying `--latest`. This argument has the same default runtime binding behavior for publishing self-contained applications. See the following example: | ||
|
|
||
| ``` console | ||
| dotnet publish -c release -o app --latest |
There was a problem hiding this comment.
what is the value of the other switches here. Either drop or write out as the reader may not remember what c and o stand for
There was a problem hiding this comment.
dropping this section
docs/core/versions/binding.md
Outdated
| You publish with a specific runtime patch version for the given target framework specifying `--version=[version]`. It is an error if this version is missing. It's an error if the given version doesn't support the target framework (as a lower bound). You may specify higher versions (even major versions), provided they exist on the machine. You can see this usage in the following example: | ||
|
|
||
| ``` console | ||
| dotnet publish -c release -o app --version=3.1.0 |
There was a problem hiding this comment.
Please tell me that syntax is incorrect. Space not equal is the normal syntax.
There was a problem hiding this comment.
We should probably use a version that we have even contemplated
There was a problem hiding this comment.
@KathleenDollard I took that paragraph from the design spec: dotnet/design2#3 It looks like this entire section (Publish an application with a specific .NET Core version) isn't implemented at all. I'm dropping this entire paragraph. Let me know if that's incorrect.
| @@ -27,6 +27,16 @@ With .NET Core 2.0, downloads show a single version number in their file name. T | |||
|
|
|||
| 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. | |||
There was a problem hiding this comment.
just a heads up. I think this is the article I'm rewriting.
"version manager" feels like quite a stretch for our experience. Since I want to build that, I'd rather change hte first bullet here
There was a problem hiding this comment.
Dropped the first bullet (this is duplicated from the versions article)
There was a problem hiding this comment.
Yeah I think this whole document needs to be reviewed / rewritten. It sounds like Kathleen is doing so.
To be clear, there is not a single version number for both the runtime and the SDK :)
BillWagner
changed the title
|
Added the WIP label. Once @livarcocc and @dsplaisted comment, I'll update based on Kathleen's comments and get it ready for final review. |
|
We made a change to global.json behavior in 2.1 This pull request explains the behavior for global.json overall. The change was what happened if an SDK version (let's say 2.0.3) was selected and that version was not on the machine, but a lower version (let's say 2.0.2) was the highest version number on the machine. Prior to 2.1 2.0.2 would run. After 2.1 this is an error. We perceived this as a bug fix. @johnbeisner can you confirm that this fix went in to 2.1.0 (and that I'm right it's a runtime deployment). This is host behavior which we install with the runtime, so you will get this behavior with .NET Core Runtime 2.1.0 or higher, regardless of the highest SDK you have. This last sentence might be too much detail for the topic. Update the SDK muxer behavior; modify the SDK muxer tests. Prior SDK muxer behavior:
Newer SDK muxer behavior:
|
Original design doc. Updated TOC Add paragraph in overview topic
BillWagner
force-pushed
the
netcore-version-binding
branch
from
2024187 to
e3f3762
Compare
Reworked the focus based on feedback. This should be simpler, more scenario focused, and more clear for users.
BillWagner
changed the title
|
Removed the 'wip' label. This is ready for another review. I took @KathleenDollard 's comments about simplicity and focus to update the headers, explain the behavior from a developer / user perspective. I think this reads much more clear. @dsplaisted @livarcocc I think I distilled the roll forward behavior correctly. I would appreciate a review for accuracy. |
docs/core/versions/binding.md
Outdated
|
|
||
| [!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 always running applications using the specified versions and enabling ease of upgrading both developer and end user machines. These policies perform the following: |
There was a problem hiding this comment.
balance between always running applications
Remove "always" here.
docs/core/versions/binding.md
Outdated
|
|
||
| ## 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. You'll use the .NET Core 99.9 SDK 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. |
There was a problem hiding this comment.
Consider using an example with real version numbers here:
You'll use the .NET Core SDK v2.1.301 if it's the highest version installed, even if the project you are working with targets the .NET Core Runtime 2.0.
docs/core/versions/binding.md
Outdated
|
|
||
| .NET Standard target frameworks are also capped in the same way. The .NET Core 2.0 SDK is capped to `netstandard2.0`. | ||
|
|
||
| You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example: |
There was a problem hiding this comment.
It feels like an abrupt jump to start talking about RuntimeFrameworkVersion here. Perhaps this belongs later in the document (after the roll forward and possibly self-contained discussion?)
There was a problem hiding this comment.
It's also important to note that RuntimeFrameworkVersion does not specify a minimum patch version, at least for self-contained apps (which is probably the main scenario for using it). For self-contained apps, the exact version specified will be used, even if there is a later patch version available.
There was a problem hiding this comment.
I moved this section to the end of the article.
There was a problem hiding this comment.
This looks pretty good overall. However, I wonder whether "binding" is the right term to use to describe the behavior. It feels like a pretty technical term that we're trying to use in docs for an audience that won't generally know what "binding" means in this context.
Could we call it "version selection" instead of "binding"?
docs/core/versions/binding.md
Outdated
| <RuntimeFrameworkVersion Condition="'$(TargetFramework)' == 'netcoreapp2.0'">2.0.4</RuntimeFrameworkVersion> | ||
| ``` | ||
|
|
||
| ## dotnet run rolls forward |
There was a problem hiding this comment.
I think this section should probably not be specific to dotnet run. It should be for running a framework-dependent app, which can be via dotnet run or via dotnet app.dll. In the .NET Core SDK 2.1.400, we will support framework-dependent deployments which include an executable which can be launched natively. So for Windows you will be able to run them by launching app.exe, and on other OS's, you would just run app.
There was a problem hiding this comment.
I changed the header to use the term "Framework-dependent apps" Is that what we want to standardize on?
docs/core/versions/binding.md
Outdated
|
|
||
| You run an application from source with [`dotnet run`](../tools/dotnet-run.md). `dotnet run` both builds and runs an application. | ||
|
|
||
| The .NET CLI chooses the latest patch version installed on the machine. For example, if you specified `netcoreapp2.0` in your project file, and `2.0.4` is the latest .NET runtime installed, the `2.0.4` runtime is used. |
There was a problem hiding this comment.
I wouldn't say it's the .NET CLI that chooses this. Usually when we say CLI we mean the .NET Core SDK, but this logic is part of the host, and applies even if you have only the runtime but not the SDK installed.
There was a problem hiding this comment.
I also added a definition of host. I tried to future-proof it a bit, but I think it will need a small update when this arrives.
docs/core/versions/binding.md
Outdated
|
|
||
| The .NET CLI chooses the latest patch version installed on the machine. For example, if you specified `netcoreapp2.0` in your project file, and `2.0.4` is the latest .NET runtime installed, the `2.0.4` runtime is used. | ||
|
|
||
| If no acceptable `2.0.*` version is found, a new `2.*` version will be used. For example, if you specified `netcoreapp2.0` and only `2.1.0` is installed, the application will run using the `2.1.0` runtime. This 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 will not run. |
There was a problem hiding this comment.
There is a duplicate "This" here
docs/core/versions/binding.md
Outdated
| A few usage examples demonstrate the behavior: | ||
|
|
||
| - 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. | ||
| - 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is printed. |
There was a problem hiding this comment.
Consider "displayed" instead of "printed"
docs/core/versions/binding.md
Outdated
| - 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. | ||
| - 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is printed. | ||
| - 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is the highest 2.x runtime version installed. 2.2.2 is used. | ||
| - 2.0.4 is required. No 2.x versions are installed. 3.0.0 is installed. An error message is printed. |
There was a problem hiding this comment.
Consider "displayed" also here.
docs/core/versions/binding.md
Outdated
| - 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. | ||
| - It's possible that 2.0.5 and 2.2.2 might behave differently, particularly for scenarios like serializing binary data. | ||
|
|
||
| All NuGet dependencies are resolved as part of the publish operation and reside as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. |
There was a problem hiding this comment.
Does this sentence serve a purpose? I would delete it. It's not entirely accurate for packages which have assemblies that are also part of .NET Core, or part of the ASP.NET Core Shared Framework.
docs/core/versions/binding.md
Outdated
|
|
||
| All NuGet dependencies are resolved as part of the publish operation and reside as assemblies (.dlls) in a flat directory structure. These assemblies should run on .NET Core 2.1 due to its compatibility promise for existing applications and binaries. | ||
|
|
||
| Developers should remember the following rules: |
There was a problem hiding this comment.
I'm not sure it's helpful to restate the logic here. I would consider deleting form here through the end of the section.
docs/core/versions/binding.md
Outdated
|
|
||
| The publishing process selects the latest patch version of the given runtime family. For example, `dotnet publish` will select .NET Core 2.0.4 if it is the latest patch version in the .NET Core 2.0 runtime family. The target framework (including the latest installed security patches) are packaged with the application. | ||
|
|
||
| It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. |
There was a problem hiding this comment.
I'd suggest linking from here to https://docs.microsoft.com/en-us/dotnet/core/deploying/runtime-patch-selection, which includes more details on roll-forward for self-contained publish.
| @@ -27,6 +27,16 @@ With .NET Core 2.0, downloads show a single version number in their file name. T | |||
|
|
|||
| 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. | |||
There was a problem hiding this comment.
Yeah I think this whole document needs to be reviewed / rewritten. It sounds like Kathleen is doing so.
To be clear, there is not a single version number for both the runtime and the SDK :)
|
Thanks for the comments @dsplaisted That cleared up my remaining questions. @KathleenDollard I did not update versions/index.md as you are rewriting that now. Will you be addressing this comment? |
|
@mairaw I believe all the changes have been addressed. Can you give this a final review? |
docs/core/versions/index.md
Outdated
| @@ -27,6 +27,15 @@ With .NET Core 2.0, downloads show a single version number in their file name. T | |||
|
|
|||
| 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 binding | |||
There was a problem hiding this comment.
It looks like renamed the document from "Binding" to "Version Selection", but the term hasn't been updated everywhere. Is this intentional?
There was a problem hiding this comment.
As I was looking at @dsplaisted 's comment, I noticed
"The use of a single version..."
would this read better as
"The use of the same version number"
or
"Using the same version number"
There was a problem hiding this comment.
@dsplaisted Got it. I had thought you meant to update "binding" for SEO, not because we weren't using the term.
@KathleenDollard Let's handle that with the next PR, based on #6081 The SDK and Runtime versions aren't aligned, so that section will change a lot.
docs/core/deploying/index.md
Outdated
| @@ -36,7 +36,7 @@ There are also a few disadvantages: | |||
|
|
|||
| ## Self-contained deployments (SCD) | |||
|
|
|||
| For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. | |||
| For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. For more information on version binding at runtime see the topic on [version binding in .NET Core](../versions/binding.md) | |||
There was a problem hiding this comment.
Change link to selection.md, and consider changing text from "binding" to "version selection" (twice).
There was a problem hiding this comment.
nit: comma between "runtime" and "see"
There was a problem hiding this comment.
- Acrolinx also always recommends article instead of topic
- Missing punctuation
- several broken links being reported by the OPS build including this one
docs/core/versions/selection.md
Outdated
| - Easy and efficient deployment of .NET Core, including security and reliability updates. | ||
| - Usage of the latest tools and commands independent of target runtime. | ||
|
|
||
| There are four activities during development and deployment where version binding occurs: |
docs/core/versions/index.md
Outdated
| @@ -27,6 +27,15 @@ With .NET Core 2.0, downloads show a single version number in their file name. T | |||
|
|
|||
| 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 binding | |||
|
|
|||
| .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 [binding](selection.md). | |||
There was a problem hiding this comment.
binding -> version selection
docs/core/versions/selection.md
Outdated
|
|
||
| ## Self-contained deployments include the selected runtime | ||
|
|
||
| You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime binding occurs at publishing time, not run-time. |
There was a problem hiding this comment.
binding -> version selection
docs/toc.md
Outdated
| @@ -120,7 +120,7 @@ | |||
| ### [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) | |||
| <!--### [🔧 Servicing](core/versions/servicing.md)--> | |||
| ### [.NET Core version binding](core/versions/selection.md) | |||
Per Product team feedback.
There was a problem hiding this comment.
This looks really good, @BillWagner. I've left a number of comments and suggestions.
docs/core/deploying/index.md
Outdated
| @@ -36,7 +36,7 @@ There are also a few disadvantages: | |||
|
|
|||
| ## Self-contained deployments (SCD) | |||
|
|
|||
| For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. | |||
| For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. For more information on version binding at runtime see the topic on [version binding in .NET Core](../versions/binding.md) | |||
There was a problem hiding this comment.
nit: comma between "runtime" and "see"
docs/core/versions/index.md
Outdated
|
|
||
| .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). | ||
|
|
||
| One can think of these policies performing the following roles: |
There was a problem hiding this comment.
One --> You
policies performing --> policies as performing
docs/core/versions/selection.md
Outdated
| 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: | ||
|
|
||
| - Easy and efficient deployment of .NET Core, including security and reliability updates. | ||
| - Usage of the latest tools and commands independent of target runtime. |
docs/core/versions/selection.md
Outdated
| - Easy and efficient deployment of .NET Core, including security and reliability updates. | ||
| - Usage of the latest tools and commands independent of target runtime. | ||
|
|
||
| There are four activities during development and deployment where version selection occurs: |
There was a problem hiding this comment.
Perhaps just simply, "Version selection occurs:"
docs/core/versions/selection.md
Outdated
| - When you [run an SDK command](#the-sdk-uses-the-latest-installed-version). | ||
| - When you [build an assembly](target-framework-monikers-define-build-time-apis). | ||
| - When you [run a .NET Core application](framework-dependent-apps-roll-forward). | ||
| - When you publish a [self-contained application](self-contained-deployments-include-the-selected-runtime). |
There was a problem hiding this comment.
This is confusing, because the descriptions don't correspond to the headers, and these categories aren't mutually exclusive. For example, running an SDK command (item 1) includes building an assembly (item 2).
docs/core/versions/selection.md
Outdated
|
|
||
| On rare occasions, you may need to use a different 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 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. |
There was a problem hiding this comment.
This is partly redundant -- there are two sentences about the CLI searching upward.
if you keep the fourth sentence, "iteratively navigating" --> iteratively by navigating"
There was a problem hiding this comment.
we usually format file names with italic. some are using backticks and some are using none.
My PR on global.json specifies the matching rules for the SDK. It has a bit more details, which I don't think should be duplicated here but perhaps at least linked to? See #4704
docs/core/versions/selection.md
Outdated
|
|
||
| The process for selecting an SDK version is: | ||
|
|
||
| - `dotnet` searches for a `global.json` file iteratively reverse-navigating the path upward from the current working directory. |
There was a problem hiding this comment.
These could be numbered rather than list items.
docs/core/versions/selection.md
Outdated
| - 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. | ||
| - 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is displayed. | ||
| - 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is the highest 2.x runtime version installed. 2.2.2 is used. | ||
| - 2.0.4 is required. No 2.x versions are installed. 3.0.0 is installed. An error message is displayed. |
There was a problem hiding this comment.
perhaps note in parens that there is no 3.0.0?
docs/core/versions/selection.md
Outdated
|
|
||
| ## Self-contained deployments include the selected runtime | ||
|
|
||
| You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime version selection occurs at publishing time, not run-time. |
There was a problem hiding this comment.
deployment, not distribution
"This approach includes .NET Core" is unclear. "...bundles the .NET Core libraries with your application"?
There was a problem hiding this comment.
nit: do not have -> don't have
run-time -> at run time
docs/core/versions/selection.md
Outdated
|
|
||
| The publishing process selects the latest patch version of the given runtime family. For example, `dotnet publish` will select .NET Core 2.0.4 if it is the latest patch version in the .NET Core 2.0 runtime family. The target framework (including the latest installed security patches) are packaged with the application. | ||
|
|
||
| It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. For more details see the article on [runtime patch selection](../deploying/runtime-patch-selection.md) in deploying .NET Core applications. |
There was a problem hiding this comment.
latest runtime --> the latest runtime
There was a problem hiding this comment.
nits; It is -> It's
is not -> isn't
does not -> doesn't
For more details ... -> use the boilerplate sentence "For more information about x, see y."
There was a problem hiding this comment.
Looks good @BillWagner. Leaving some comments for you to address before merging. Don't forget to check the build report.
docs/core/deploying/index.md
Outdated
| @@ -36,7 +36,7 @@ There are also a few disadvantages: | |||
|
|
|||
| ## Self-contained deployments (SCD) | |||
|
|
|||
| For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. | |||
| For a self-contained deployment, you deploy your app and any required third-party dependencies along with the version of .NET Core that you used to build the app. Creating an SCD doesn't include the [native dependencies of .NET Core](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) on various platforms, so these must be present before the app runs. For more information on version binding at runtime see the topic on [version binding in .NET Core](../versions/binding.md) | |||
There was a problem hiding this comment.
- Acrolinx also always recommends article instead of topic
- Missing punctuation
- several broken links being reported by the OPS build including this one
docs/core/versions/selection.md
Outdated
| @@ -0,0 +1,110 @@ | |||
| --- | |||
| title: .NET Core version selection | |||
| description: Learn How .NET Core finds and chooses runtime versions for your program. | |||
docs/core/versions/selection.md
Outdated
|
|
||
| On rare occasions, you may need to use a different 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 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. |
There was a problem hiding this comment.
we usually format file names with italic. some are using backticks and some are using none.
My PR on global.json specifies the matching rules for the SDK. It has a bit more details, which I don't think should be duplicated here but perhaps at least linked to? See #4704
docs/core/versions/selection.md
Outdated
| The process for selecting an SDK version is: | ||
|
|
||
| - `dotnet` searches for a `global.json` file iteratively reverse-navigating the path upward from the current working directory. | ||
| - `dotnet` uses the SDK specified in the first `global.json` found. |
There was a problem hiding this comment.
wondering if we should say tries to use the SDK specified in the first global.json found following the matching rules? this routine can thrown an error if an appropriate SDK is not found
There was a problem hiding this comment.
I added that link, but I may remove if it causes a build error until #4704 is merged.
docs/core/versions/selection.md
Outdated
|
|
||
| ## 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 in the project file. Set the `TargetFramework` element in your project file as shown in the following example: |
There was a problem hiding this comment.
docs/core/versions/selection.md
Outdated
| A few usage examples demonstrate the behavior: | ||
|
|
||
| - 2.0.4 is required. 2.0.5 is the highest patch version available. 2.0.5 is used. | ||
| - 2.0.4 is required. No 2.0.* versions are installed. 1.1.1 is the highest runtime installed. An error message is displayed. |
There was a problem hiding this comment.
do we also need an example with 2.0.0 installed?
docs/core/versions/selection.md
Outdated
| Minor version roll-forward has one side-effect that may affect end users. Consider the following scenario: | ||
|
|
||
| - 2.0.4 is required. No 2.0.* versions are installed. 2.2.2 is installed. 2.2.2 is used. | ||
| - 2.0.5 is later installed. 2.0.5 will be used for subsequent application launches, not 2.2.2. |
There was a problem hiding this comment.
Yes, that's correct: it uses the patch instead of an updated minor version. Added a clarifying sentence.
There was a problem hiding this comment.
That was a suggestion 😊 to say not 2.2.2 any longer or something to that extent.
docs/core/versions/selection.md
Outdated
|
|
||
| ## Self-contained deployments include the selected runtime | ||
|
|
||
| You can publish an application as a [**self-contained distribution**](../deploying/index.md#self-contained-deployments-scd). This approach includes .NET Core. Self-contained distributions do not have a dependency on runtime environments. Runtime version selection occurs at publishing time, not run-time. |
There was a problem hiding this comment.
nit: do not have -> don't have
run-time -> at run time
docs/core/versions/selection.md
Outdated
|
|
||
| The publishing process selects the latest patch version of the given runtime family. For example, `dotnet publish` will select .NET Core 2.0.4 if it is the latest patch version in the .NET Core 2.0 runtime family. The target framework (including the latest installed security patches) are packaged with the application. | ||
|
|
||
| It is an error if the minimum version specified for an application is not satisfied. `dotnet publish` binds to latest runtime patch version (within a given major.minor version family). `dotnet publish` does not support the roll-forward semantics of `dotnet run`. For more details see the article on [runtime patch selection](../deploying/runtime-patch-selection.md) in deploying .NET Core applications. |
There was a problem hiding this comment.
nits; It is -> It's
is not -> isn't
does not -> doesn't
For more details ... -> use the boilerplate sentence "For more information about x, see y."
docs/core/versions/selection.md
Outdated
|
|
||
| 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* patch level of the framework. | ||
|
|
||
| When you target multiple frameworks, you must specify the minimum runtime patch version to the specific target framework, as shown in the following example for .NET Core: |
There was a problem hiding this comment.
Apparently, it just works. (Spec is no longer correct). Deleting this paragraph.
|
@rpetrusha Thanks for all the feedback (and @mairaw ) I've addressed all the comments, and this should be ready to go. |
|
closing & reopening for wip check |
There was a problem hiding this comment.
This looks really good, @BillWagner. You can merge when you're ready.
|
closing and reopening so that PR (hopefully) will be mergeable |
|
The last commit message contains "WIP". That seems to be blocking. |
|
I think, @BillWagner, that the PR is blocked because of your last commit message. |
This can get added back later, once dotnet#4704 is approved.
BillWagner
force-pushed
the
netcore-version-binding
branch
from
bada458 to
9fd3e15
Compare
Fixed #2880
The first commit adds the design document without changes. The second and third commit represent edits from spec to docs.