Pacotes, metapacotes e estruturasPackages, metapackages, and frameworks

O .NET Core é uma plataforma composta por pacotes NuGet..NET Core is a platform made of NuGet packages. Algumas experiências de produtos aproveitam melhor a definição refinada de pacotes, enquanto para outros a alta granularidade é melhor.Some product experiences benefit from fine-grained definition of packages while others from coarse-grained. Para acomodar essa duplaidade, o .NET Core é distribuído como um conjunto refinado de pacotes e em partes mais grosseiras com um tipo de pacote informalmente chamado de metapacote.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.

Cada um dos pacotes do .NET Core dá suporte à execução em várias implementações do .NET, representadas como estruturas.Each of the .NET Core packages supports being run on multiple .NET implementations, represented as frameworks. Algumas dessas estruturas são estruturas tradicionais, como net46, que representa o .NET Framework.Some of those frameworks are traditional frameworks, like net46, which represents the .NET Framework. Outro conjunto são as novas estruturas que podem ser consideradas como "estruturas baseadas em pacote", que estabelecem um novo modelo para definir estruturas.Another set is new frameworks that can be thought of as "package-based frameworks", which establish a new model for defining frameworks. Essas estruturas baseadas em pacote são totalmente criadas e definidas como pacotes, formando uma relação forte entre pacotes e estruturas.These package-based frameworks are entirely created and defined as packages, forming a strong relationship between packages and frameworks.

PacotesPackages

O .NET Core é dividido em um conjunto de pacotes que fornecem primitivos, tipos de dados de nível superior, tipos de composição de aplicativo e utilitários comuns..NET Core is split into a set of packages that provide primitives, higher-level data types, app composition types, and common utilities. Cada um desses pacotes representa um único assembly de mesmo nome.Each of these packages represents a single assembly of the same name. Por exemplo, o pacote System. Runtime contém System. Runtime. dll.For example, the System.Runtime package contains System.Runtime.dll.

Há vantagens em definir pacotes de forma refinada:There are advantages to defining packages in a fine-grained manner:

  • Pacotes refinados podem ser fornecidos em seu próprio cronograma, com testes relativamente limitados de outros pacotes.Fine-grained packages can ship on their own schedule with relatively limited testing of other packages.
  • Pacotes refinados podem fornecer suporte a sistemas operacionais e CPUs diferentes.Fine-grained packages can provide differing OS and CPU support.
  • Pacotes refinados podem ter dependências específicas em apenas uma biblioteca.Fine-grained packages can have dependencies specific to only one library.
  • Os aplicativos são menores, pois os pacotes não referenciados não se tornam parte da distribuição do aplicativo.Apps are smaller because unreferenced packages don't become part of the app distribution.

Alguns desses benefícios são usados somente em determinadas circunstâncias.Some of these benefits are only used in certain circumstances. Por exemplo, pacotes .NET Core geralmente são fornecidos no mesmo cronograma que o suporte de plataforma.For example, NET Core packages will typically ship on the same schedule with the same platform support. No caso de manutenção, as correções podem ser distribuídas e instaladas como atualizações de único pacote pequeno.In the case of servicing, fixes can be distributed and installed as small single package updates. Devido ao escopo restrito de alteração, a validação e o tempo para disponibilizar uma correção ficam limitados ao que é necessário para uma única biblioteca.Due to the narrow scope of change, the validation and time to make a fix available is limited to what is needed for a single library.

Veja a seguir uma lista dos principais pacotes NuGet para .NET Core:The following is a list of the key NuGet packages for .NET Core:

Normalmente, em vez de incluir cada pacote, é mais fácil e mais robusto incluir um metapacote.Typically, rather than including each package, it's easier and more robust to include a metapackage. No entanto, quando você precisa de um único pacote, é possível incluí-lo como no exemplo a seguir, fazendo referência ao pacote System.Runtime.However, when you need a single package, you can include it as in the following example, which references the System.Runtime package.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard1.6</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="System.Runtime" Version="4.3.0" />
  </ItemGroup>
</Project>

MetapacotesMetapackages

Um metapacote é uma Convenção de pacote NuGet para descrever um conjunto de pacotes que são significativos em conjunto.A metapackage is a NuGet package convention for describing a set of packages that are meaningful together. Um metapacote representa esse conjunto de pacotes, tornando-os dependências.A metapackage represents this set of packages by making them dependencies. O metapacote pode, opcionalmente, estabelecer uma estrutura para o conjunto de pacotes, especificando uma estrutura.The metapackage can optionally establish a framework for the set of packages by specifying a framework.

Por padrão, as versões anteriores das ferramentas do .NET Core (ferramentas baseadas em project.json e csproj) especificavam uma estrutura e um metapacote.Previous versions of the .NET Core tools (both project.json and csproj-based tools) by default specified both a framework and a metapackage. Atualmente, no entanto, o metapacote é referenciado implicitamente pela estrutura de destino, para que cada metapacote seja vinculado a uma estrutura de destino.Currently, however, the metapackage is implicitly referenced by the target framework, so that each metapackage is tied to a target framework. Por exemplo, a estrutura netstandard1.6 referencia o metapacote NetStandard.Library versão 1.6.0.For example, the netstandard1.6 framework references the NetStandard.Library version 1.6.0 metapackage. Da mesma forma, a estrutura netcoreapp2.1 referencia o metapacote Microsoft.NETCore.App Versão 2.1.0.Similarly, the netcoreapp2.1 framework references the Microsoft.NETCore.App Version 2.1.0 metapackage. Para obter mais informações, consulte Referência implícita de pacote de metapacote no SDK do .NET Core.For more information, see Implicit metapackage package reference in the .NET Core SDK.

Direcionar uma estrutura e referenciar implicitamente um metapacote significa que, na verdade, você está adicionando uma referência a cada um de seus pacotes dependentes como um único gesto.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. Isso disponibiliza todas as bibliotecas nesses pacotes para o IntelliSense (ou uma experiência semelhante) e para publicação do aplicativo.That makes all of the libraries in those packages available for IntelliSense (or similar experience) and for publishing your app.

Há vantagens em usar metapacotes:There are advantages to using metapackages:

  • Fornece uma experiência de usuário conveniente para fazer referência a um grande conjunto de pacotes refinados.Provides a convenient user experience to reference a large set of fine-grained packages.
  • Define um conjunto de pacotes (incluindo versões específicas) que são testados e funcionam bem em conjunto.Defines a set of packages (including specific versions) that are tested and work well together.

O metapacote da .NET Standard é:The .NET Standard metapackage is:

  • Netstandard. library -descreve as bibliotecas que fazem parte do .net Standard.NETStandard.Library - Describes the libraries that are part of .NET Standard. Aplica-se a todas as implementações do .NET que dão suporte a .NET Standard (por exemplo, .NET Framework, .NET Core e mono).Applies to all .NET implementations that support .NET Standard (for example, .NET Framework, .NET Core, and Mono). Estabelece a estrutura de netstandard.Establishes the netstandard framework.

Os principais metapacotes do .NET Core são:The key .NET Core metapackages are:

FrameworksFrameworks

Cada pacote do .NET Core dá suporte a um conjunto de estruturas de runtime..NET Core packages each support a set of runtime frameworks. As estruturas descrevem um conjunto de APIs disponível (e possivelmente outras características) com os quais você pode contar ao direcionar uma determinada estrutura.Frameworks describe an available API set (and potentially other characteristics) that you can rely on when you target a given framework. Eles têm controle de versão à medida que novas APIs são adicionadas.They are versioned as new APIs are added.

Por exemplo, System.IO.FileSystem dá suporte às seguintes estruturas:For example, System.IO.FileSystem supports the following frameworks:

  • .NETFramework,Version=4.6.NETFramework,Version=4.6
  • .NETStandard,Version=1.3.NETStandard,Version=1.3
  • Plataformas 6 Xamarin (por exemplo, xamarinios10)6 Xamarin platforms (for example, xamarinios10)

É útil comparar as duas primeiras dessas estruturas, pois são exemplos das duas maneiras diferentes pelas quais as estruturas são definidas:It's useful to contrast the first two of these frameworks, since they are examples of the two different ways that frameworks are defined:

  • A estrutura de .NETFramework,Version=4.6 representa as APIs disponíveis no .NET Framework 4,6.The .NETFramework,Version=4.6 framework represents the available APIs in .NET Framework 4.6. Você pode produzir bibliotecas compiladas com os assemblies de referência do .NET Framework 4,6 e, em seguida, distribuir essas bibliotecas em pacotes NuGet em uma pasta net46 lib.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. Ele será usado para aplicativos direcionados .NET Framework 4,6 ou que são compatíveis com ele.It will be used for apps that target .NET Framework 4.6 or that are compatible with it. Essa é a maneira como todas as estruturas tradicionalmente funcionam.This is how all frameworks have traditionally worked.

  • A estrutura .NETStandard,Version=1.3 é uma estrutura baseada em pacote.The .NETStandard,Version=1.3 framework is a package-based framework. Ela se baseia em pacotes direcionados para a estrutura definir e expor as APIs com relação à estrutura.It relies on packages that target the framework to define and expose APIs in terms of the framework.

Estruturas baseadas em pacotePackage-based frameworks

Há uma relação bidirecional entre estruturas e pacotes.There is a two-way relationship between frameworks and packages. A primeira parte é definir as APIs disponíveis para uma determinada estrutura, por exemplo netstandard1.3.The first part is defining the APIs available for a given framework, for example netstandard1.3. Pacotes direcionados a netstandard1.3 (ou estruturas compatíveis, como o netstandard1.0) definem as APIs disponíveis para netstandard1.3.Packages that target netstandard1.3 (or compatible frameworks, like netstandard1.0) define the APIs available for netstandard1.3. Isso pode parecer uma definição circular, mas não é.That may sound like a circular definition, but it isn't. Por ser "baseada em pacote", a definição da API para a estrutura vem dos pacotes.By virtue of being "package-based", the API definition for the framework comes from packages. A estrutura em si não define nenhuma APIs.The framework itself doesn't define any APIs.

A segunda parte da relação é a seleção de ativo.The second part of the relationship is asset selection. Pacotes podem conter ativos para várias estruturas.Packages can contain assets for multiple frameworks. Dada uma referência a um conjunto de pacotes e/ou metapacotes, a estrutura é necessária para determinar qual ativo será selecionado, por exemplo net46 ou netstandard1.3.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. É importante selecionar o ativo correto.It's important to select the correct asset. Por exemplo, um ativo net46 provavelmente não é compatível com .NET Framework 4.0 ou .NET Core 1.0.For example, a net46 asset is not likely to be compatible with .NET Framework 4.0 or .NET Core 1.0.

Veja essa relação na imagem a seguir.You can see this relationship in the following image. A API é voltada para a estrutura e a define.The API targets and defines the framework. A estrutura é usada para seleção de ativo.The framework is used for asset selection. O ativo fornece a API.The asset gives you the API.

Composição de estrutura baseada em pacote

As duas principais estruturas baseadas em pacote usadas com o .NET Core são:The two primary package-based frameworks used with .NET Core are:

  • netstandard
  • netcoreapp

.NET Standard.NET Standard

A estrutura .NET Standard (target Framework moniker: netstandard) representa as APIs definidas pelo e criadas com base em .net Standard.The .NET Standard (Target Framework Moniker: netstandard) framework represents the APIs defined by and built on top of .NET Standard. Bibliotecas destinadas a execução em vários runtimes devem ter essa estrutura como alvo.Libraries that are intended to run on multiple runtimes should target this framework. Eles terão suporte em qualquer tempo de execução compatível com .NET Standard, como .NET Core, .NET Framework e mono/Xamarin.They will be supported on any .NET Standard-compliant runtime, such as .NET Core, .NET Framework, and Mono/Xamarin. Cada um desses runtimes dá suporte a um conjunto de versões do .NET Standard, dependendo de quais APIs eles implementam.Each of these runtimes supports a set of .NET Standard versions, depending on which APIs they implement.

A estrutura netstandard faz referência implícita ao metapacote NETStandard.Library.The netstandard framework implicitly references the NETStandard.Library metapackage. Por exemplo, o arquivo de projeto do MSBuild a seguir indica que o projeto é direcionado ao netstandard1.6, que faz referência ao metapacote NETStandard.Library versão 1.6.For example, the following MSBuild project file indicates that the project targets netstandard1.6, which references the NETStandard.Library version 1.6 metapackage.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard1.6</TargetFramework>
  </PropertyGroup>
</Project>

No entanto, as referências de estrutura e de metapacote no arquivo de projeto não precisam ser correspondentes e é possível usar o elemento <NetStandardImplicitPackageVersion> no arquivo de projeto para especificar uma versão de estrutura inferior à versão do metapacote.However, the framework and metapackage references in the project file do not need to match, and you can use the <NetStandardImplicitPackageVersion> element in your project file to specify a framework version that is lower than the metapackage version. Por exemplo, o arquivo de projeto a seguir é válido.For example, the following project file is valid.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard1.3</TargetFramework>
    <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
  </PropertyGroup>
</Project>

Pode parecer estranho apontar para netstandard1.3, mas use a versão 1.6.0 do NETStandard.Library.It may seem strange to target netstandard1.3 but use the 1.6.0 version of NETStandard.Library. Esse é um caso de uso válido, pois o metapacote mantém o suporte para versões mais antigas do netstandard.It is a valid use-case, since the metapackage maintains support for older netstandard versions. Pode ser o caso de você já ter padronizado a versão 1.6.0 do metapacote e tê-la usado para todas as suas bibliotecas, que são voltadas para diversas versões do netstandard.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. Com essa abordagem, você só precisará restaurar a NETStandard.Library 1.6.0 e não versões anteriores.With this approach, you only need to restore NETStandard.Library 1.6.0 and not earlier versions.

O inverso não seria válido: direcionar netstandard1.6 com a versão 1.3.0 do NETStandard.Library.The reverse would not be valid: targeting netstandard1.6 with the 1.3.0 version of NETStandard.Library. Você não pode direcionar uma estrutura mais elevada com um metapacote menos elevado, visto que a versão do metapacote inferior não exporá os ativos para essa estrutura superior.You cannot target a higher framework with a lower metapackage, since the lower version metapackage will not expose any assets for that higher framework. O esquema de controle de versão para metapacotes declara que os metapacotes correspondem à versão mais alta da estrutura descrita por eles.The versioning scheme for metapackages asserts that metapackages match the highest version of the framework they describe. Devido a esse esquema de controle de versão, a primeira versão do NETStandard.Library é v1.6.0, já que ele contém ativos netstandard1.6.By virtue of the versioning scheme, the first version of NETStandard.Library is v1.6.0 given that it contains netstandard1.6 assets. (Para simetria com o exemplo anterior, v 1.3.0 é usado aqui, mas ele não existe de fato.)(For symmetry with the previous example, v1.3.0 is used here, but it doesn't actually exist.)

Aplicativo .NET Core.NET Core application

A estrutura do .NET Core (Moniker da Estrutura de Destino: netcoreapp) representa os pacotes e APIs associadas que são fornecidos com a distribuição do .NET Core e o modelo de aplicativo de console que ela fornece.The .NET Core (Target Framework Moniker: netcoreapp) framework represents the packages and associated APIs that come with the .NET Core distribution and the console application model that it provides. Aplicativos .NET Core devem usar essa estrutura, devido ao direcionamento do modelo de aplicativo de console, assim como as bibliotecas que devem ser executados apenas em .NET Core..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. Usar essa estrutura restringe a bibliotecas à execução apenas no .NET Core.Using this framework restricts apps and libraries to running only on .NET Core.

O metapacote Microsoft.NETCore.App é direcionado para a estrutura netcoreapp.The Microsoft.NETCore.App metapackage targets the netcoreapp framework. Ele fornece acesso a ~60 bibliotecas, ~ 40 fornecida pelo pacote NETStandard.Library e mais ~20 adicionais.It provides access to ~60 libraries, ~40 provided by the NETStandard.Library package and ~20 more in addition. Você pode referenciar outras bibliotecas direcionadas ao netcoreapp ou estruturas compatíveis, como o netstandard, para obter acesso a APIs adicionais.You can reference additional libraries that target netcoreapp or compatible frameworks, such as netstandard, to get access to additional APIs.

A maioria das bibliotecas adicionais fornecidas pelo Microsoft.NETCore.App também são direcionadas para netstandard, considerando que suas dependências foram atendidas por outras bibliotecas netstandard.Most of the additional libraries provided by Microsoft.NETCore.App also target netstandard given that their dependencies are satisfied by other netstandard libraries. Isso significa que bibliotecas netstandard também podem fazer referência a esses pacotes como dependências.That means that netstandard libraries can also reference those packages as dependencies.