Frameworks and Targets update #1721

guardrex · 2017-03-13T19:54:15Z

Topic renamed to Target Frameworks
NuGet docs topic content added to this topic
Link this topic to commands was handled in Fix-up dotnet command docs #1705

dnfclas · 2017-03-13T19:54:19Z

@guardrex,
Thanks for having already signed the Contribution License Agreement. Your agreement was validated by .NET Foundation. We will now review your pull request.
Thanks,
.NET Foundation Pull Request Bot

mairaw · 2017-03-17T00:46:26Z

docs/standard/frameworks.md


-## Framework Versions
+Refernece | Name


typo: Refernece

also, this feels a bit lost here without the explanation we had before.

mairaw · 2017-03-17T00:46:47Z

docs/standard/frameworks.md


-The table below defines the set of frameworks that you can use, how they are referred to and which version of the [.NET Standard Library](library.md) that they implement.
+## Lastest framework versions


typo: lastest

mairaw · 2017-03-17T00:47:18Z

docs/standard/frameworks.md

-| .NET Standard | 1.6 | .NETStandard,Version=1.6 | netstandard1.6 | N/A | [NETStandard.Library](https://www.nuget.org/packages/NETStandard.Library)|
-| .NET Core Application | 1.0.1 | .NETCoreApp,Version=1.0 | netcoreapp1.0 | 1.6 | [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App)|
-| .NET Framework | 4.6.2 | .NETFramework,Version=4.6.2 | net462 | 1.5 | N/A |
+The table below defines the set of frameworks that you can use, how they're referenced, and which version of the [.NET Standard Library](library.md) they implement. These framework versions are the latest stable versions. Pre-release versions aren't shown.


The table below -> The following table (style guide rule)

mairaw · 2017-03-17T00:55:57Z

docs/standard/frameworks.md

+ | | netstandard1.4
+ | | netstandard1.5
+ | | netstandard1.6
+.NET Core App | netcoreapp | netcoreapp1.0


we're missing netcoreapp1.1 here

also wondering if we should move netstandard and netcoreapp higher in the list.

mairaw · 2017-03-17T00:57:54Z

@terrajobst can you help review this? also, where can I find where the TFMs are defined? I wanted to double-check this list.

mairaw

a few comments

mairaw · 2017-03-17T00:58:30Z

docs/standard/frameworks.md

+ | | netstandard1.4
+ | | netstandard1.5
+ | | netstandard1.6
+.NET Core App | netcoreapp | netcoreapp1.0


also wondering if we should move netstandard and netcoreapp higher in the list.

mairaw · 2017-03-17T00:59:26Z

docs/standard/frameworks.md

+ | | net46
+ | | net461
+ | | net462
+.NET Core | netcore | netcore [netcore45]


what does the netcore TFM is used for? having it identified as .NET Core could be confusing. @terrajobst

Depreciated .NET Core TFM's? ... that haven't been formally moved to the "depreciated" list yet because some libs perhaps still use them??? wildly guessing

I'll wait on @terrajobst help on this one. I think it has to do with UWP.

mairaw · 2017-03-17T01:02:10Z

docs/standard/frameworks.md


-You can refer to a family of frameworks using long- or short-forms of the framework ID. Both are equally valid in the general case.
+The [.NET Standard](https://github.com/dotnet/standard) simplifies references between binary-compatible frameworks, allowing a single target framework to reference a combination of others. For background, see the [.NET Platform Guide](https://docs.microsoft.com/dotnet/articles/standard/index).


use relative link to topics inside the repo. and probably a better link is this: https://docs.microsoft.com/en-us/dotnet/articles/standard/library. I'll submit a PR to the NuGet docs for this.

mairaw · 2017-03-17T01:03:40Z

docs/standard/frameworks.md

+
+For NuGet 3.3 and earlier, use the `dotnet` series of monikers. For NuGet 3.4 and later, use the `netstandard` moniker syntax.
+
+## Portable Class Libraries


this one is a really long list and we don't even recommend people using it anymore. I think in this case we could link to the NuGet topic (https://docs.microsoft.com/nuget/schema/target-frameworks#portable-class-libraries)

mairaw · 2017-03-17T01:04:56Z

docs/standard/frameworks.md

-title: Frameworks and Targets
-description: Explains the concepts of framework targets when writing .NET code.
-keywords: .NET, .NET Core
+title: Target frameworks


.NET Target Frameworks | Microsoft Docs (no need to add the .NET for the H1)

mairaw

some minor comments. almost ready to go. I just want to clarify the netcore vs. netcoreapp TFMs more clearly. and I'm also trying to find out where these are defined so we can double check if the list is complete.

mairaw · 2017-03-21T00:52:59Z

docs/standard/frameworks.md

+ | | netstandard1.4
+ | | netstandard1.5
+ | | netstandard1.6
+.NET Core App | netcoreapp | netcoreapp1.0 | netcoreapp1.1


.netcoreapp1.1 should be in a new row

mairaw · 2017-03-21T00:59:56Z

docs/standard/frameworks.md

+ | | net46
+ | | net461
+ | | net462
+.NET Core | netcore | netcore [netcore45]


I'll wait on @terrajobst help on this one. I think it has to do with UWP.

mairaw · 2017-03-21T01:00:29Z

docs/standard/frameworks.md

-keywords: .NET, .NET Core
+title: Target frameworks | Microsoft Docs
+description: Explains the concepts of target frameworks when writing .NET code.
+keywords: .NET, .NET Core, framework, tfm


svick · 2017-03-23T16:28:11Z

docs/standard/frameworks.md

+:--------: | :--: | :--: | :--: | :--: | :--: | :--:
+.NET Standard | 1.6.1 | .NETStandard,Version=1.6 | netstandard1.6 | N/A | [NETStandard.Library](https://www.nuget.org/packages/NETStandard.Library)
+.NET Core Application | 1.1.1 | .NETCoreApp,Version=1.1 | netcoreapp1.1 | 1.6 | [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App)
+.NET Framework | 4.6.2 | .NETFramework,Version=4.6.2 | net462 | 1.5 | N/A


This table doesn't seem to render properly on GitHub (probably caused by the recent GitHub change).

Probably the exterior pipes ... they aren't technically required, but I already had one table 💥 on me without them. I'll add them back here and see if that does the trick.

I found the prob with this ... it's not the exterior pipes ... the columns are literally wrong. I'll fix it.

svick · 2017-03-23T16:45:13Z

docs/standard/frameworks.md

+
+The [.NET Standard](https://github.com/dotnet/standard) simplifies references between binary-compatible frameworks, allowing a single target framework to reference a combination of others. For background, see the [.NET Standard Library](library.md).
+
+The [NuGet Tools Get Nearest Framework Tool](https://aka.ms/s2m3th) simulates the NuGet logic used for the selection of one framework from many available framework assets in a package based on the project's framework. To use the tool, enter one project framework and one or more package frameworks. Click the **Submit** button. The tool indicates if the package frameworks you list are compatible with the project framework you provide.


This seems to link to version 3.5.0-beta2-1484 of the tool, when versions 3.5.0 and 4.0.0 are available. Shouldn't the link be changed to one of those?

Yes, great catch! I'll fix it. Let's just go with http://nugettoolsdev.azurewebsites.net/, since the latest framework is loaded ✨ auto-magically ✨

svick · 2017-03-23T16:48:17Z

docs/standard/frameworks.md

+
+The [NuGet Tools Get Nearest Framework Tool](https://aka.ms/s2m3th) simulates the NuGet logic used for the selection of one framework from many available framework assets in a package based on the project's framework. To use the tool, enter one project framework and one or more package frameworks. Click the **Submit** button. The tool indicates if the package frameworks you list are compatible with the project framework you provide.
+
+For NuGet 3.3 and earlier, use the `dotnet` series of monikers. For NuGet 3.4 and later, use the `netstandard` moniker syntax.


Is information on how to use an old version of NuGet still useful?

I'd remove it since the dotnet ones already show up as deprecated earlier

svick · 2017-03-23T16:49:59Z

docs/standard/frameworks.md

+ xamarinwatchos | Xamarin for Watch OS | netstandard1.4
+ xamarintvos | Xamarin for TV OS | netstandard1.4
+ xamarinxboxthreesixty | Xamarin for XBox 360 | netstandard1.4
+ xamarinxboxone | Xamarin for XBox One | netstandard1.4


What does this table do here? It doesn't seem to be related to the paragraph right before it. Shouldn't it have some sort of text introduction?

I cut what @mairaw said to cut. @mairaw, do you want to cut this one?

yes, this is also part of the PCL section on the NuGet docs

guardrex · 2017-03-23T18:29:00Z

Thanks @svick ... I think that licked it.

We decided to clean up tables generally as we go. Future generations will thank us!

mairaw · 2017-03-24T00:17:37Z

docs/standard/frameworks.md

+
+The .NET ecosystem has a concept of *target frameworks*. Frameworks define the API that you can use to target a particular platform. For example, the .NET Framework 4.6 is a platform that you can target. Visual Studio and other IDEs and editors use frameworks to provide you with the correct set of APIs. NuGet also uses them to ensure that you produce and consume appropriate NuGet packages and underlying assets for the framework you're targeting.
+
+| Reference | Name                                      |


I thought I had commented it before but couldn't find it. This information seems lost here compared to how the information was presented before.

I did make an attempt to rewrite it to make sense ... and failed 😢. I'll pull up the text from my prior attempt and see where I left off with it.

When you say "how the information was presented before," that predates me here. This is the way I found it sans the two sentences at the end that I stripped off.

I thought this was you rewriting the Writing about Frameworks section which is shown on the diff, no?

guardrex · 2017-03-24T07:02:31Z

@mairaw Oh, yes. I see what you mean now. I thought you were referring to the first paragraph. I brought back the Writing about frameworks section with upgrades. The table was meant simply to condense all of it, but I like this layout, too. I think we know who influenced my earlier decision cough cough Rick cough. 😀

I plopped that alternative frameworks language in here for feedback. cc/ @weshaggard @terrajobst

mairaw

I've left a few last comments for you to address before merging but this is a big improvement IMO. Thanks @guardrex!

mairaw · 2017-04-27T06:08:26Z

docs/standard/frameworks.md


-## Framework Versions
+The terms *framework* and *platform* are sometimes confusing given how they're used in phrases. Making interpretation worse, the term *platform* has different meanings in different contexts. For example, you'll see ".NET Core" described as the ".NET Core framework" in the context of building apps and libraries and also described as the ".NET Core platform" in the context of where app and library code is executed. A *computing platform* describes *where and how* an application is run. Since .NET Core executes code with the [.NET Core Common Language Runtime (CoreCLR)](https://github.com/dotnet/coreclr), it's also a platform. The same is true of the .NET Framework, which has the [Common Language Runtime (CLR)](https://msdn.microsoft.com/library/8bs2ecf4(v=vs.110).aspx) to execute app and library code that was developed with the .NET Framework's framework objects, methods, and tools. You'll frequently see the term "cross-platform" in documentation; but when you see that term, you should think "cross-operating system and cross-architecture (x86, x64, arm)," because that's the meaning that the author usually intends to convey.


https://msdn.microsoft.com/library/8bs2ecf4(v=vs.110).aspx -> https://github.com/dotnet/docs/blob/master/docs/standard/clr.md

mairaw · 2017-04-27T06:12:51Z

docs/standard/frameworks.md

-| .NET Standard | 1.6 | .NETStandard,Version=1.6 | netstandard1.6 | N/A | [NETStandard.Library](https://www.nuget.org/packages/NETStandard.Library)|
-| .NET Core Application | 1.0.1 | .NETCoreApp,Version=1.0 | netcoreapp1.0 | 1.6 | [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App)|
-| .NET Framework | 4.6.2 | .NETFramework,Version=4.6.2 | net462 | 1.5 | N/A |
+When you *target a framework* or target several of them, you've decided which set(s) of APIs and which version(s) of those APIs you would like to use. Frameworks are referenced in several ways: by product name, by long- or short-form framework names, and by family.


style guide rule about adding (s) to make plural: Don't add (s) or (es) to a singular noun to indicate that it can be singular or plural. Most of the time, use plural instead. If it's important to indicate both, use one or more.

mairaw · 2017-04-27T06:16:22Z

docs/standard/frameworks.md

+| Windows Store              | netcore      | netcore [netcore45]                          |
+|                            |              | netcore45 [win, win8]                        |
+|                            |              | netcore451 [win81]                           |
+| .NET MicroFramework        | netmf        | netmf                                        |


space between Micro and framework

Luke Latham added 2 commits March 11, 2017 00:37

Initial commit

c7b2e04

Updates

3a7e0fc

guardrex added enhancement labels Mar 13, 2017

guardrex added this to the March 2017 milestone Mar 13, 2017

guardrex self-assigned this Mar 13, 2017

dnfclas added the cla-already-signed label Mar 13, 2017

mairaw reviewed Mar 17, 2017

View reviewed changes

mairaw requested changes Mar 17, 2017

View reviewed changes

React to feedback

2b410c2

mairaw requested a review from terrajobst March 21, 2017 00:55

mairaw requested changes Mar 21, 2017

View reviewed changes

Luke Latham added 2 commits March 20, 2017 22:13

React to feedback

1ff006d

Update table format

ef96c0d

svick reviewed Mar 23, 2017

View reviewed changes

React to feedback, table fixup, and minor updates

02f04c5

Luke Latham added 2 commits March 23, 2017 18:13

Remove netcore series of TFMs

ae1ea7d

Add back netcore<50 TFMs

3d87596

mairaw reviewed Mar 24, 2017

View reviewed changes

Luke Latham added 4 commits March 24, 2017 01:08

Updates

034e4b2

Updates

0b2bac6

Updates

1bac929

Updates

e3d5102

mairaw removed this from the March 2017 milestone Mar 29, 2017

mairaw approved these changes Apr 27, 2017

View reviewed changes

React to feedback

b570fa7

guardrex closed this May 1, 2017

guardrex reopened this May 1, 2017

dnfclas added the cla-already-signed label May 1, 2017

mairaw merged commit 45835eb into dotnet:master May 1, 2017

mairaw deleted the guardrex/frameworks-topic-update branch May 1, 2017 17:49


		The table below defines the set of frameworks that you can use, how they are referred to and which version of the [.NET Standard Library](library.md) that they implement.
		## Lastest framework versions


		You can refer to a family of frameworks using long- or short-forms of the framework ID. Both are equally valid in the general case.
		The [.NET Standard](https://github.com/dotnet/standard) simplifies references between binary-compatible frameworks, allowing a single target framework to reference a combination of others. For background, see the [.NET Platform Guide](https://docs.microsoft.com/dotnet/articles/standard/index).


		For NuGet 3.3 and earlier, use the `dotnet` series of monikers. For NuGet 3.4 and later, use the `netstandard` moniker syntax.

		## Portable Class Libraries


		The [.NET Standard](https://github.com/dotnet/standard) simplifies references between binary-compatible frameworks, allowing a single target framework to reference a combination of others. For background, see the [.NET Standard Library](library.md).

		The [NuGet Tools Get Nearest Framework Tool](https://aka.ms/s2m3th) simulates the NuGet logic used for the selection of one framework from many available framework assets in a package based on the project's framework. To use the tool, enter one project framework and one or more package frameworks. Click the Submit button. The tool indicates if the package frameworks you list are compatible with the project framework you provide.


		The .NET ecosystem has a concept of target frameworks. Frameworks define the API that you can use to target a particular platform. For example, the .NET Framework 4.6 is a platform that you can target. Visual Studio and other IDEs and editors use frameworks to provide you with the correct set of APIs. NuGet also uses them to ensure that you produce and consume appropriate NuGet packages and underlying assets for the framework you're targeting.

		\| Reference \| Name \|


		## Framework Versions
		The terms framework and platform are sometimes confusing given how they're used in phrases. Making interpretation worse, the term platform has different meanings in different contexts. For example, you'll see ".NET Core" described as the ".NET Core framework" in the context of building apps and libraries and also described as the ".NET Core platform" in the context of where app and library code is executed. A computing platform describes where and how an application is run. Since .NET Core executes code with the [.NET Core Common Language Runtime (CoreCLR)](https://github.com/dotnet/coreclr), it's also a platform. The same is true of the .NET Framework, which has the [Common Language Runtime (CLR)](https://msdn.microsoft.com/library/8bs2ecf4(v=vs.110).aspx) to execute app and library code that was developed with the .NET Framework's framework objects, methods, and tools. You'll frequently see the term "cross-platform" in documentation; but when you see that term, you should think "cross-operating system and cross-architecture (x86, x64, arm)," because that's the meaning that the author usually intends to convey.

Frameworks and Targets update #1721

Frameworks and Targets update #1721

Conversation

guardrex commented Mar 13, 2017

dnfclas commented Mar 13, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mairaw commented Mar 17, 2017

mairaw left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mairaw Mar 17, 2017 • edited Loading

Choose a reason for hiding this comment

guardrex Mar 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mairaw left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Mar 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guardrex commented Mar 24, 2017

mairaw left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mairaw Mar 17, 2017 •

edited

Loading

guardrex Mar 17, 2017 •

edited

Loading