Skip to content

Commit

Permalink
Small tweaks to metapackages (dotnet#16903)
Browse files Browse the repository at this point in the history 
* small improvements

* does not -> doesn't

Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>
  • Loading branch information
@gewarren @mairaw
gewarren and mairaw committed Jan 31, 2020
1 parent 8eee41b commit 12bd8a8
Showing 1 changed file with 19 additions and 20 deletions.
39 changes: 19 additions & 20 deletions docs/core/packages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,13 @@ ms.date: 06/20/2016
---
# Packages, metapackages, and frameworks

.NET Core is a platform made of NuGet packages. Some product experiences benefit from fine-grained definition of packages while others from coarse-grained. To accommodate this duality, the product is distributed as a fine-grained set of packages and in coarser chunks with a package type informally called a [metapackage](#metapackages).
.NET Core is a platform made of NuGet packages. Some product experiences benefit from fine-grained definition of packages while others from coarse-grained. To accommodate this duality, .NET Core is distributed as a fine-grained set of packages and in coarser chunks with a package type informally called a [metapackage](#metapackages).

Each of the .NET Core packages support being run on multiple .NET implementations, represented as
frameworks. Some of those frameworks are traditional frameworks, like `net46`, representing the .NET Framework. Another set is new frameworks that can be thought of as "package-based frameworks", which establish a new model for defining frameworks. These package-based frameworks are entirely formed and defined as packages, forming a strong relationship between packages and frameworks.
Each of the .NET Core packages supports being run on multiple .NET implementations, represented as frameworks. Some of those frameworks are traditional frameworks, like `net46`, which represents the .NET Framework. Another set is new frameworks that can be thought of as "package-based frameworks", which establish a new model for defining frameworks. These package-based frameworks are entirely created and defined as packages, forming a strong relationship between packages and frameworks.

## Packages

.NET Core is split into a set of packages that provide primitives, higher-level data types, app composition types, and common utilities. Each of these packages represents a single assembly of the same name. For example, the [System.Runtime package](https://www.nuget.org/packages/System.Runtime) contains System.Runtime.dll.
.NET Core is split into a set of packages that provide primitives, higher-level data types, app composition types, and common utilities. Each of these packages represents a single assembly of the same name. For example, the [System.Runtime package](https://www.nuget.org/packages/System.Runtime) contains System.Runtime.dll.

There are advantages to defining packages in a fine-grained manner:

Expand All @@ -33,7 +32,7 @@ The following is a list of the key NuGet packages for .NET Core:
- [System.Linq](https://www.nuget.org/packages/System.Linq) - A set of types for querying objects, including `Enumerable` and <xref:System.Linq.ILookup%602>.
- [System.Reflection](https://www.nuget.org/packages/System.Reflection) - A set of types for loading, inspecting, and activating types, including <xref:System.Reflection.Assembly>, <xref:System.Reflection.TypeInfo> and <xref:System.Reflection.MethodInfo>.

Typically, rather than including each package, it's easier and more robust to include a [metapackage](#metapackages). However, when you need a single package, you can include it as in the following example, which references the [System.Runtime](https://www.nuget.org/packages/System.Runtime/) package.
Typically, rather than including each package, it's easier and more robust to include a [metapackage](#metapackages). However, when you need a single package, you can include it as in the following example, which references the [System.Runtime](https://www.nuget.org/packages/System.Runtime/) package.

```xml
<Project Sdk="Microsoft.NET.Sdk">
Expand All @@ -48,24 +47,24 @@ Typically, rather than including each package, it's easier and more robust to in

## Metapackages

Metapackages are a NuGet package convention for describing a set of packages that are meaningful together. They represent this set of packages by making them dependencies. They can optionally establish a framework for this set of packages by specifying a framework.
A metapackage is a NuGet package convention for describing a set of packages that are meaningful together. A metapackage represents this set of packages by making them dependencies. The metapackage can optionally establish a framework for the set of packages by specifying a framework.

Previous versions of the .NET Core tools (both project.json and csproj-based tools) by default specified both a framework and a metapackage. Currently, however, the metapackage is implicitly referenced by the target framework, so that each metapackage is tied to a target framework. For example, the `netstandard1.6` framework references the NetStandard.Library version 1.6.0 metapackage. Similarly, the `netcoreapp2.1` framework references the Microsoft.NETCore.App Version 2.1.0 metapackage. For more information, see [Implicit metapackage package reference in the .NET Core SDK](https://github.com/dotnet/core/blob/master/release-notes/1.0/sdk/1.0-rc3-implicit-package-refs.md).

Targeting a framework and implicitly referencing a metapackage means that you in effect are adding a reference to each of its dependent packages as a single gesture. That makes all of the libraries in those packages available for IntelliSense (or similar experience) and for publishing your app.
Targeting a framework and implicitly referencing a metapackage means that, in effect, you are adding a reference to each of its dependent packages as a single gesture. That makes all of the libraries in those packages available for IntelliSense (or similar experience) and for publishing your app.

There are advantages to using metapackages:

- Provides a convenient user experience to reference a large set of fine-grained packages.
- Provides a convenient user experience to reference a large set of fine-grained packages.
- Defines a set of packages (including specific versions) that are tested and work well together.

The .NET Standard metapackage is:

- [NETStandard.Library](https://www.nuget.org/packages/NETStandard.Library) - Describes the libraries that are part of the ".NET Standard". Applies to all .NET implementations (for example, .NET Framework, .NET Core and Mono) that support .NET Standard. Establishes the 'netstandard' framework.
- [NETStandard.Library](https://www.nuget.org/packages/NETStandard.Library) - Describes the libraries that are part of .NET Standard. Applies to all .NET implementations that support .NET Standard (for example, .NET Framework, .NET Core, and Mono). Establishes the `netstandard` framework.

The key .NET Core metapackages are:

- [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) - Describes the libraries that are part of the .NET Core distribution. Establishes the [`.NETCoreApp` framework](https://github.com/dotnet/core-setup/blob/release/1.1.0/pkg/projects/Microsoft.NETCore.App/Microsoft.NETCore.App.pkgproj). Depends on the smaller `NETStandard.Library`.
- [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) - Describes the libraries that are part of the .NET Core distribution. Establishes the `.NETCoreApp` framework. Depends on the smaller `NETStandard.Library`.
- [Microsoft.AspNetCore.App](https://www.nuget.org/packages/Microsoft.AspNetCore.App) - Includes all the supported packages from ASP.NET Core and Entity Framework Core except those that contain third-party dependencies. See [Microsoft.AspNetCore.App metapackage for ASP.NET Core](/aspnet/core/fundamentals/metapackage-app) for more information.
- [Microsoft.AspNetCore.All](https://www.nuget.org/packages/Microsoft.AspNetCore.All) - Includes all the supported packages from ASP.NET Core, Entity Framework Core, and internal and third-party dependencies used by ASP.NET Core and Entity Framework Core. See [Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.x](/aspnet/core/fundamentals/metapackage) for more information.
- [Microsoft.NETCore.Portable.Compatibility](https://www.nuget.org/packages/Microsoft.NETCore.Portable.Compatibility) - A set of compatibility facades that enable mscorlib-based Portable Class Libraries (PCLs) to run on .NET Core.
Expand All @@ -80,17 +79,17 @@ For example, [System.IO.FileSystem](https://www.nuget.org/packages/System.IO.Fil
- .NETStandard,Version=1.3
- 6 Xamarin platforms (for example, xamarinios10)

It is useful to contrast the first two of these frameworks, since they are examples of the two different ways that frameworks are defined.
It's useful to contrast the first two of these frameworks, since they are examples of the two different ways that frameworks are defined:

The `.NETFramework,Version=4.6` framework represents the available APIs in the .NET Framework 4.6. You can produce libraries compiled with the .NET Framework 4.6 reference assemblies and then distribute those libraries in NuGet packages in a net46 lib folder. It will be used for apps that target the .NET Framework 4.6 or that are compatible with it. This is how all frameworks have traditionally worked.
- The `.NETFramework,Version=4.6` framework represents the available APIs in .NET Framework 4.6. You can produce libraries compiled with the .NET Framework 4.6 reference assemblies, and then distribute those libraries in NuGet packages in a net46 lib folder. It will be used for apps that target .NET Framework 4.6 or that are compatible with it. This is how all frameworks have traditionally worked.

The `.NETStandard,Version=1.3` framework is a package-based framework. It relies on packages that target the framework to define and expose APIs in terms of the framework.
- The `.NETStandard,Version=1.3` framework is a package-based framework. It relies on packages that target the framework to define and expose APIs in terms of the framework.

## Package-based frameworks

There is a two-way relationship between frameworks and packages. The first part is defining the APIs available for a given framework, for example `netstandard1.3`. Packages that target `netstandard1.3` (or compatible frameworks, like `netstandard1.0`) define the APIs available for `netstandard1.3`. That may sound like a circular definition, but it isn't. By virtue of being "package-based", the API definition for the framework comes from packages. The framework itself doesn't define any APIs.

The second part of the relationship is asset selection. Packages can contain assets for multiple frameworks. Given a reference to a set of packages and/or metapackages, the framework is needed to determine which asset should be selected, for example `net46` or `netstandard1.3`. It is important to select the correct asset. For example, a `net46` asset is not likely to be compatible with .NET Framework 4.0 or .NET Core 1.0.
The second part of the relationship is asset selection. Packages can contain assets for multiple frameworks. Given a reference to a set of packages and/or metapackages, the framework is needed to determine which asset should be selected, for example `net46` or `netstandard1.3`. It's important to select the correct asset. For example, a `net46` asset is not likely to be compatible with .NET Framework 4.0 or .NET Core 1.0.

You can see this relationship in the following image. The *API* targets and defines the *framework*. The *framework* is used for *asset selection*. The *asset* gives you the API.

Expand All @@ -103,7 +102,7 @@ The two primary package-based frameworks used with .NET Core are:

### .NET Standard

The .NET Standard ([Target Framework Moniker](../standard/frameworks.md): `netstandard`) framework represents the APIs defined by and built on top of the [.NET Standard](../standard/net-standard.md). Libraries that are intended to run on multiple runtimes should target this framework. They will be supported on any .NET Standard-compliant runtime, such as .NET Core, .NET Framework, and Mono/Xamarin. Each of these runtimes supports a set of .NET Standard versions, depending on which APIs they implement.
The .NET Standard ([Target Framework Moniker](../standard/frameworks.md): `netstandard`) framework represents the APIs defined by and built on top of [.NET Standard](../standard/net-standard.md). Libraries that are intended to run on multiple runtimes should target this framework. They will be supported on any .NET Standard-compliant runtime, such as .NET Core, .NET Framework, and Mono/Xamarin. Each of these runtimes supports a set of .NET Standard versions, depending on which APIs they implement.

The `netstandard` framework implicitly references the [`NETStandard.Library`](https://www.nuget.org/packages/NETStandard.Library) metapackage. For example, the following MSBuild project file indicates that the project targets `netstandard1.6`, which references the [`NETStandard.Library` version 1.6](https://www.nuget.org/packages/NETStandard.Library/1.6.0) metapackage.

Expand All @@ -126,14 +125,14 @@ However, the framework and metapackage references in the project file do not nee
</Project>
```

It may seem strange to target `netstandard1.3` but use the 1.6.0 version of `NETStandard.Library`. It is a valid use-case, since the metapackage maintains support for older `netstandard` versions. It could be the case you've standardized on the 1.6.0 version of the metapackage and use it for all your libraries, which target a variety of `netstandard` versions. With this approach, you only need to restore `NETStandard.Library` 1.6.0 and not earlier versions.
It may seem strange to target `netstandard1.3` but use the 1.6.0 version of `NETStandard.Library`. It is a valid use-case, since the metapackage maintains support for older `netstandard` versions. It could be the case you've standardized on the 1.6.0 version of the metapackage and use it for all your libraries, which target a variety of `netstandard` versions. With this approach, you only need to restore `NETStandard.Library` 1.6.0 and not earlier versions.

The reverse would not be valid: targeting `netstandard1.6` with the 1.3.0 version of `NETStandard.Library`. You cannot target a higher framework with a lower metapackage, since the lower version metapackage will not expose any assets for that higher framework. The versioning scheme for metapackages asserts that metapackages match the highest version of the framework they describe. By virtue of the versioning scheme, the first version of `NETStandard.Library` is v1.6.0 given that it contains `netstandard1.6` assets. v1.3.0 is used in the example above, for symmetry with the example above, but does not actually exist.
The reverse would not be valid: targeting `netstandard1.6` with the 1.3.0 version of `NETStandard.Library`. You cannot target a higher framework with a lower metapackage, since the lower version metapackage will not expose any assets for that higher framework. The versioning scheme for metapackages asserts that metapackages match the highest version of the framework they describe. By virtue of the versioning scheme, the first version of `NETStandard.Library` is v1.6.0 given that it contains `netstandard1.6` assets. (For symmetry with the previous example, v1.3.0 is used here, but it doesn't actually exist.)

### .NET Core application

The .NET Core ([Target Framework Moniker](../standard/frameworks.md): `netcoreapp`) framework represents the packages and associated APIs that come with the .NET Core distribution and the console application model that it provides. .NET Core apps must use this framework, due to targeting the console application model, as should libraries that intended to run only on .NET Core. Using this framework restricts apps and libraries to running only on .NET Core.
The .NET Core ([Target Framework Moniker](../standard/frameworks.md): `netcoreapp`) framework represents the packages and associated APIs that come with the .NET Core distribution and the console application model that it provides. .NET Core apps must use this framework, due to targeting the console application model, as should libraries that intended to run only on .NET Core. Using this framework restricts apps and libraries to running only on .NET Core.

The `Microsoft.NETCore.App` metapackage targets the `netcoreapp` framework. It provides access to ~60 libraries, ~40 provided by the `NETStandard.Library` package and ~20 more in addition. You can reference additional libraries that target `netcoreapp` or compatible frameworks, such as `netstandard`, to get access to additional APIs.
The `Microsoft.NETCore.App` metapackage targets the `netcoreapp` framework. It provides access to ~60 libraries, ~40 provided by the `NETStandard.Library` package and ~20 more in addition. You can reference additional libraries that target `netcoreapp` or compatible frameworks, such as `netstandard`, to get access to additional APIs.

Most of the additional libraries provided by `Microsoft.NETCore.App` also target `netstandard` given that their dependencies are satisfied by other `netstandard` libraries. That means that `netstandard` libraries can also reference those packages as dependencies.
Most of the additional libraries provided by `Microsoft.NETCore.App` also target `netstandard` given that their dependencies are satisfied by other `netstandard` libraries. That means that `netstandard` libraries can also reference those packages as dependencies.

0 comments on commit 12bd8a8

Please sign in to comment.