Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
As referências de pacote, usando <PackageReference> itens do MSBuild, especificam as dependências do pacote NuGet diretamente nos arquivos de projeto, em vez de ter um ficheiro separado packages.config. O uso de PackageReference não afeta outros aspetos do NuGet; por exemplo, as configurações em NuGet.Config arquivos (incluindo fontes de pacote) ainda são aplicadas conforme explicado em Configurações comuns do NuGet.
Com PackageReference, você também pode usar as condições do MSBuild para escolher referências de pacote por estrutura de destino ou outros agrupamentos. Ele também permite um controle refinado sobre dependências e fluxo de conteúdo. (Para obter mais informações, consulte NuGet pack and restore as MSBuild targets.)
Apoio ao tipo de projeto
Por padrão, PackageReference é usado para projetos .NET, projetos .NET Standard e projetos UWP destinados ao Windows 10 Build 15063 (Creators Update) e posteriores, com exceção de projetos UWP C++. Os projetos do .NET Framework oferecem suporte a PackageReference, mas atualmente o padrão é .packages.config Para usar PackageReference em um projeto do .NET Framework, migre as dependências para o arquivo de packages.config projeto e remova packages.config.
ASP.NET aplicativos destinados ao .NET Framework completo incluem apenas suporte limitado para PackageReference. Os tipos de projeto C++ e JavaScript não são suportados.
Adicionando uma referência de pacote
Adicione uma dependência em seu arquivo de projeto usando a seguinte sintaxe:
<ItemGroup>
<!-- ... -->
<PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
<!-- ... -->
</ItemGroup>
Controlando a versão de dependência
A convenção para especificar a versão de um pacote é a mesma que quando se usa packages.config:
<ItemGroup>
<!-- ... -->
<PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
<!-- ... -->
</ItemGroup>
No exemplo acima, 3.6.0 significa qualquer versão que seja >=3.6.0 com preferência para a versão mais baixa, conforme descrito em Controle de versão de pacote.
Usando PackageReference para um projeto sem dependências de pacote
Avançado: Se você não tiver pacotes instalados em um projeto (nenhum PackageReferences no arquivo de projeto e nenhum arquivo packages.config), mas quiser que o projeto seja restaurado como estilo PackageReference, você pode definir uma propriedade Project RestoreProjectStyle como PackageReference em seu arquivo de projeto.
<PropertyGroup>
<!--- ... -->
<RestoreProjectStyle>PackageReference</RestoreProjectStyle>
<!--- ... -->
</PropertyGroup>
Isso pode ser útil se você fizer referência a projetos com estilo PackageReference (projetos existentes no estilo csproj ou SDK). Isso permitirá que os pacotes aos quais esses projetos se referem sejam referenciados "transitivamente" pelo seu projeto.
PackageReference e fontes
Em projetos PackageReference, as versões de dependência transitiva são resolvidas no momento da restauração. Como tal, em projetos PackageReference, todas as fontes precisam estar disponíveis para todas as restaurações.
Versões flutuantes
As versões flutuantes são suportadas com PackageReference:
<ItemGroup>
<!-- ... -->
<PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
<PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta.*" />
<!-- ... -->
</ItemGroup>
Controlando ativos de dependência
Você pode estar a usar uma dependência puramente como uma ferramenta de desenvolvimento e talvez não queira expô-la a projetos que consumirão o seu pacote. Nesse cenário, você pode usar os PrivateAssets metadados para controlar esse comportamento.
<ItemGroup>
<!-- ... -->
<PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
<PrivateAssets>all</PrivateAssets>
</PackageReference>
<!-- ... -->
</ItemGroup>
As seguintes tags de metadados controlam ativos de dependência:
| Tag | Description | Valor padrão |
|---|---|---|
| IncludeAssets | Estes ativos serão consumidos | all |
| ExcludeAssets | Estes ativos não serão consumidos | none |
| PrivateAssets | Esses ativos serão consumidos, mas não fluirão para o projeto pai | contentfiles;analyzers;build |
Os valores permitidos para essas tags são os seguintes, com vários valores separados por um ponto-e-vírgula, exceto para all e none, que devem aparecer por si mesmos:
| Value | Description |
|---|---|
| Compilar | Conteúdo da pasta e controla lib se seu projeto pode compilar em relação aos assemblies dentro da pasta |
| runtime | Conteúdos das pastas lib e runtimes e controla se estas assemblagens serão copiadas para o diretório de saída da compilação |
| contentFiles | Conteúdo da contentfiles pasta |
| compilação |
.props e .targets na build pasta |
| buildMultitargeting |
(4.0).props e .targets na buildMultitargeting pasta, para direcionamento entre plataformas |
| buildTransitive |
(5,0+).props e .targets na buildTransitive pasta, para ativos que fluem transitivamente para qualquer projeto consumidor. Consulte a página do recurso . |
| analyzers | Analisadores .NET |
| nativo | Conteúdo da native pasta |
| none | Nenhuma das opções acima é usada. |
| all | Todos os itens acima (exceto none) |
<ItemGroup>
<!-- ... -->
<!-- Everything except the content files will be consumed by the project -->
<!-- Everything except content files and analyzers will flow to the parent project-->
<PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
<IncludeAssets>all</IncludeAssets> <!-- Default is `all`, can be omitted-->
<ExcludeAssets>contentFiles</ExcludeAssets>
<PrivateAssets>contentFiles;analyzers</PrivateAssets>
</PackageReference>
<!-- ... -->
<!-- Everything except the compile will be consumed by the project -->
<!-- Everything except contentFiles will flow to the parent project-->
<PackageReference Include="Contoso.Utility.SomeOtherUsefulStuff" Version="3.6.0">
<ExcludeAssets>compile</ExcludeAssets>
<PrivateAssets>contentFiles</PrivateAssets>
</PackageReference>
<!-- ... -->
</ItemGroup>
Observe que, porque build não está incluído com PrivateAssets, os alvos e elementos fluirão para o projeto pai. Considere, por exemplo, que a referência acima é usada em um projeto que cria um pacote NuGet chamado AppLogger. O AppLogger pode consumir os destinos e props do Contoso.Utility.UsefulStuff, assim como os projetos que consomem o AppLogger.
Note
Quando developmentDependency é definido como true em um .nuspec arquivo, isso marca um pacote como uma dependência somente de desenvolvimento, o que impede que o pacote seja incluído como uma dependência em outros pacotes. Com PackageReference (NuGet 4.8+), esse sinalizador também significa que ele excluirá ativos em tempo de compilação da compilação. Para obter mais informações, consulte Suporte DevelopmentDependency para PackageReference.
Adicionando uma condição PackageReference
Você pode usar uma condição para controlar se um pacote está incluído. As condições podem usar qualquer variável MSBuild ou uma variável definida no arquivo targets ou props. No entanto, atualmente, apenas a TargetFramework variável é suportada.
Por exemplo, digamos que você está segmentando netstandard1.4 tão bem net452 , mas tem uma dependência que é aplicável apenas para net452. Nesse caso, você não quer que um netstandard1.4 projeto que consome seu pacote adicione essa dependência desnecessária. Para evitar isso, especifique uma condição no PackageReference da seguinte maneira:
<ItemGroup>
<!-- ... -->
<PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
<!-- ... -->
</ItemGroup>
Um pacote criado usando este projeto mostrará que Newtonsoft.Json está incluído como uma dependência apenas para um net452 destino:
As condições também podem ser aplicadas ao nível ItemGroup e aplicar-se-ão a todos os elementos filhos PackageReference.
<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
<!-- ... -->
<PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
<PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
<!-- ... -->
</ItemGroup>
GeneratePathProperty
Esse recurso está disponível com o NuGet 5.0 ou superior e com o Visual Studio 2019 16.0 ou superior.
Às vezes, é desejável fazer referência a ficheiros num pacote a partir de um destino MSBuild.
Em projetos baseados em packages.config, os pacotes são instalados numa diretoria relativa ao arquivo de projeto. No entanto, em PackageReference, os pacotes são consumidos da pasta global-packages, a qual pode variar de máquina para máquina.
Para preencher essa lacuna, o NuGet introduziu uma propriedade que aponta para o local a partir do qual o pacote será consumido.
Example:
<ItemGroup>
<PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
</ItemGroup>
<Target Name="TakeAction" AfterTargets="Build">
<Exec Command="$(PkgSome_Package)\something.exe" />
</Target>
Além disso, o NuGet gera automaticamente propriedades para pacotes que contêm uma pasta de ferramentas.
<ItemGroup>
<PackageReference Include="Package.With.Tools" Version="1.0.0" />
</ItemGroup>
<Target Name="TakeAction" AfterTargets="Build">
<Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
</Target>
As propriedades e identidades de pacote do MSBuild não têm as mesmas restrições, portanto, a identidade do pacote precisa ser alterada para um nome amigável do MSBuild, prefixado pela palavra Pkg.
Para verificar o nome exato da propriedade gerada, veja o arquivo nuget.g.props gerado.
Aliases PackageReference
Em alguns casos raros, pacotes diferentes conterão classes no mesmo namespace. A partir do NuGet 5.7 & Visual Studio 2019 Update 7, equivalente a ProjectReference, PackageReference suporta Aliases.
Por padrão, nenhum aliases é fornecido. Quando um alias é especificado, todos os assemblies provenientes do pacote anotado precisam ser referenciados com um alias.
Você pode examinar o uso de exemplo em NuGet\Samples.
No arquivo de projeto, especifique os aliases da seguinte maneira:
<ItemGroup>
<PackageReference Include="NuGet.Versioning" Version="5.8.0" Aliases="ExampleAlias" />
</ItemGroup>
E no código, use-o da seguinte forma:
extern alias ExampleAlias;
namespace PackageReferenceAliasesExample
{
...
{
var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0");
Console.WriteLine($"Version : {version}");
}
...
}
Avisos e erros do NuGet
Esse recurso está disponível com o NuGet 4.3 ou superior e com o Visual Studio 2017 15.3 ou superior.
Para muitos cenários de pacote e restauração, todos os avisos e erros do NuGet são codificados e começam com NU****. Todos os avisos e erros do NuGet estão listados na documentação de referência .
O NuGet observa as seguintes propriedades de aviso:
-
TreatWarningsAsErrors, trate todos os avisos como erros. -
WarningsAsErrors, trate avisos específicos como erros. -
NoWarn, esconda avisos específicos, seja a nível de projeto ou a nível de pacote.
Examples:
<PropertyGroup>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
<WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
<NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
<PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>
Supressão de avisos do NuGet
Embora seja recomendável que resolva todos os avisos do NuGet nas suas operações de empacotamento e restauração, em determinadas situações é justificável suprimi-los. Para suprimir um aviso em todo o projeto, considere fazer:
<PropertyGroup>
<PackageVersion>5.0.0</PackageVersion>
<NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>
Por vezes, os avisos aplicam-se apenas a um determinado pacote no gráfico. Você pode optar por suprimir esse aviso de forma mais seletiva adicionando um NoWarn no item PackageReference.
<PropertyGroup>
<PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>
Suprimindo avisos de pacote NuGet no Visual Studio
Quando estiver no Visual Studio, você também pode suprimir avisos por meio do IDE.
Bloqueando dependências
Esse recurso está disponível com o NuGet 4.9 ou superior e com o Visual Studio 2017 15.9 ou superior.
A entrada para a restauração do NuGet é um conjunto de itens do arquivo de PackageReference projeto (dependências diretas ou de nível superior) e a saída é um fechamento completo de todas as dependências do pacote, incluindo dependências transitivas. O NuGet tenta sempre produzir o mesmo fechamento completo das dependências do pacote se a lista PackageReference de entrada não tiver sido alterada. No entanto, existem alguns cenários em que não é possível fazê-lo. Por exemplo:
Quando você usa versões flutuantes como
<PackageReference Include="My.Sample.Lib" Version="4.*"/>. Embora a intenção aqui seja flutuar para a versão mais recente em cada restauração de pacotes, há cenários em que os usuários exigem que o gráfico seja bloqueado para uma determinada versão mais recente e flutue para uma versão posterior, se disponível, mediante um gesto explícito.Uma versão mais recente do pacote correspondente aos requisitos de versão PackageReference é publicada. Por exemplo:
Dia 1: se você especificou
<PackageReference Include="My.Sample.Lib" Version="4.0.0"/>, mas as versões disponíveis nos repositórios do NuGet eram 4.1.0, 4.2.0 e 4.3.0. Neste caso, o NuGet teria resolvido para 4.1.0 (versão mínima mais próxima).Dia 2: A versão 4.0.0 é publicada. O NuGet agora encontrará a correspondência exata e começará a resolver para a versão 4.0.0.
Uma determinada versão do pacote é removida do repositório. Embora nuget.org não permita exclusões de pacotes, nem todos os repositórios de pacotes têm essa restrição. Isso faz com que o NuGet encontre a melhor solução quando não conseguir resolver para a versão eliminada.
Ativando o arquivo de bloqueio
Para persistir o fechamento total das dependências do pacote, você pode optar pelo recurso de arquivo de bloqueio definindo a propriedade RestorePackagesWithLockFile MSBuild para seu projeto:
<PropertyGroup>
<!--- ... -->
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
<!--- ... -->
</PropertyGroup>
Se essa propriedade estiver definida, a restauração do NuGet gerará um arquivo de bloqueio (packages.lock.json) no diretório raiz do projeto que lista todas as dependências do pacote.
Note
Uma vez que um projeto tem packages.lock.json o arquivo em seu diretório raiz, o arquivo de bloqueio é sempre usado com restauração, mesmo que a propriedade RestorePackagesWithLockFile não esteja definida. Portanto, outra maneira de optar por esse recurso é criar um arquivo em branco packages.lock.json fictício no diretório raiz do projeto.
restore Comportamento com arquivo de bloqueio
Se um arquivo de bloqueio estiver presente para um projeto, o NuGet usará esse arquivo de bloqueio para executar restoreo . O NuGet faz uma verificação rápida para ver se houve alguma alteração nas dependências do pacote, conforme mencionado no arquivo de projeto (ou nos arquivos de projetos dependentes), e se não houver alterações, ele apenas restaura os pacotes mencionados no arquivo de bloqueio. Não há reavaliação das dependências dos pacotes.
Se o NuGet detetar uma alteração nas dependências definidas, conforme mencionado no(s) arquivo(s) de projeto, ele reavaliará o gráfico do pacote e atualizará o arquivo de bloqueio para refletir o novo fechamento do pacote para o projeto.
Para CI/CD e outros cenários, onde você não gostaria de alterar as dependências do pacote em tempo real, você pode fazer isso definindo o lockedmode como true:
Para dotnet.exe, execute:
> dotnet.exe restore --locked-mode
Para msbuild.exe, execute:
> msbuild.exe -t:restore -p:RestoreLockedMode=true
Você também pode definir essa propriedade MSBuild condicional em seu arquivo de projeto:
<PropertyGroup>
<!--- ... -->
<RestoreLockedMode>true</RestoreLockedMode>
<!--- ... -->
</PropertyGroup>
Se o modo bloqueado for true, a restauração restaurará os pacotes exatos conforme listados no arquivo de bloqueio ou falhará se você atualizou as dependências de pacote definidas para o projeto após a criação do arquivo de bloqueio.
Bloquear arquivos e PrunePackageReference
PrunePackageReference altera as dependências de um projeto, removendo pacotes transitivos desnecessários. Embora a remoção desses pacotes não deva ter um impacto no tempo de execução, isso afetará os arquivos de bloqueio. Se ativar a poda para um projeto existente, sempre que o arquivo de bloqueio for regenerado, isso poderá resultar em um menor número de pacotes do que antes da poda. A verificação de atualização do ficheiro de bloqueio que impulsiona o modo bloqueado é sensível à remoção, o que significa que, se activares a poda num projeto, a verificação irá considerar os pacotes que foram podados. No entanto, da próxima vez que o arquivo de bloqueio for regenerado, ele excluirá os pacotes removidos, para que você possa ver uma comparação maior do que o normal.
Tornar o arquivo de bloqueio parte do repositório de origem
Se você estiver criando um aplicativo, um executável e o projeto em questão estiver no início da cadeia de dependência, faça check-in do arquivo de bloqueio no repositório de código-fonte para que o NuGet possa usá-lo durante a restauração.
No entanto, se o seu projeto for um projeto de biblioteca que você não envia ou um projeto de código comum do qual outros projetos dependem, você não deve fazer check-in do arquivo de bloqueio como parte do seu código-fonte. Não há nenhum dano em manter o arquivo de bloqueio, mas as dependências de pacote bloqueado para o projeto de código comum não podem ser usadas, conforme listado no arquivo de bloqueio, durante a restauração/compilação de um projeto que depende desse projeto de código comum.
Example:
ProjectA
|------> PackageX 2.0.0
|------> ProjectB
|------>PackageX 1.0.0
Se ProjectA tiver uma dependência em uma PackageX versão 2.0.0 e também referências ProjectB que dependem da PackageX versão 1.0.0, então o arquivo de bloqueio para ProjectB listará uma dependência na PackageX versão 1.0.0. No entanto, quando ProjectA é criado, seu arquivo de bloqueio conterá uma dependência na PackageX versão 2.0.0 e não1.0.0 conforme listado no arquivo de bloqueio para ProjectB. Assim, o arquivo de bloqueio de um projeto de código comum tem pouca influência sobre os pacotes resolvidos para projetos que dependem dele.
Bloquear a extensibilidade do arquivo
Você pode controlar vários comportamentos de restauração com o arquivo de bloqueio conforme descrito abaixo:
| NuGet.exe opção | opção dotnet | Opção equivalente ao MSBuild | Description |
|---|---|---|---|
-UseLockFile |
--use-lock-file |
RestorePackagesWithLockFile | Opta pelo uso de um arquivo de bloqueio. |
-LockedMode |
--locked-mode |
RestoreLockedMode | Habilita o modo bloqueado para restauração. Isso é útil em cenários de CI/CD onde você deseja compilações repetíveis. |
-ForceEvaluate |
--force-evaluate |
RestoreForceEvaluate | Esta opção é útil com pacotes com versão flutuante definida no projeto. Por padrão, a restauração do NuGet não atualizará a versão do pacote automaticamente em cada restauração, a menos que você execute a restauração com essa opção. |
-LockFilePath |
--lock-file-path |
NuGetLockFilePath | Define um local de arquivo de bloqueio personalizado para um projeto. Por padrão, o NuGet é compatível com packages.lock.json no diretório raiz. Se você tiver vários projetos no mesmo diretório, o NuGet oferece suporte ao arquivo de bloqueio específico do projeto packages.<project_name>.lock.json |
Resolvedor de dependência do NuGet
O resolvedor de dependência NuGet segue as quatro regras descritas no documento de resolução de dependência.
Para melhorar o desempenho e a escalabilidade da operação de restauração, o algoritmo de restauração foi reescrito na versão 6.12.
A partir da versão 6.12, o novo algoritmo de restauração é habilitado por padrão para todos os projetos PackageReference.
Embora o novo algoritmo de restauração seja funcionalmente equivalente ao anterior, como com qualquer software, bugs são possíveis.
Para reverter para a implementação anterior, defina a propriedade RestoreUseLegacyDependencyResolver MSBuild como true.
Se você enfrentar falhas de restauração na versão 6.12, .NET 9 ou 17.12, que não estavam sendo reproduzidas em versões anteriores, registre um problema no GitHub. Quaisquer diferenças entre os algoritmos antigos e novos podem ter impactos diferentes, como durante a compilação ou em tempo de execução. Há também uma chance de que as alterações não levem a falhas, mas diferentes versões de pacotes sejam restauradas. Se você acha que pode ser afetado por quaisquer alterações, aqui estão as etapas que você pode seguir para verificar se as alterações no algoritmo de restauração do NuGet são a causa raiz.
Restore grava seus resultados no MSBuildProjectExtensionsPath diretório, que pode ser comparado com os algoritmos novos e antigos para encontrar diferenças.
Normalmente, esta é a obj pasta da sua compilação.
Você pode usar msbuild.exe ou dotnet.exe para as próximas etapas.
Remova a
objpasta do seu projeto.Executar
msbuild -t:restoreSalve o conteúdo do
objnum local indicando tratar-se do comportamentonew.Execute
msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true".Salve o conteúdo do
objnum local indicando tratar-se do comportamentolegacy.Compare os arquivos nos dois diretórios, particularmente project.assets.json.
Ferramentas que podem destacar diferenças são especialmente úteis para isso (por exemplo, no Visual Studio Code, abra ambos os arquivos e use o botão direito do mouse "selecionar para comparar" e "comparar para selecionado").
Se você seguir o método acima, deve haver exatamente 1 diferença entre os project.assets.json arquivos:
"projectStyle": "PackageReference",
+ "restoreUseLegacyDependencyResolver": true,
"fallbackFolders": [
Se houver mais diferenças, registre um problema no GitHub com todos os detalhes.
AssetTargetFallback
A AssetTargetFallback propriedade permite especificar versões de estrutura compatíveis adicionais para projetos que seu projeto faz referência e pacotes NuGet que seu projeto consome.
Se você especificar uma dependência de pacote usando PackageReference , mas esse pacote não contiver ativos compatíveis com a estrutura de destino de seus projetos, a AssetTargetFallback propriedade entrará em ação. A compatibilidade do pacote referenciado é verificada novamente usando cada estrutura de destino especificada em AssetTargetFallback.
Quando a project ou a package é referenciado através AssetTargetFallbackdo , o aviso NU1701 será gerado.
Consulte a tabela abaixo para obter exemplos de como AssetTargetFallback afeta a compatibilidade.
| Estrutura do projeto | AssetTargetFallback | Estruturas de pacotes | Result |
|---|---|---|---|
| .NET Framework 4.7.2 | .NET Padrão 2.0 | .NET Padrão 2.0 | |
| Aplicativo .NET Core 3.1 | .NET Standard 2.0, .NET Framework 4.7.2 | .NET Padrão 2.0 | |
| Aplicativo .NET Core 3.1 | .NET Framework 4.7.2 | Incompatível, falha com NU1202 |
|
| Aplicativo .NET Core 3.1 | net472;net471 | .NET Framework 4.7.2 | .NET Framework 4.7.2 com NU1701 |
Várias estruturas podem ser especificadas usando ; como um delimitador. Para adicionar uma estrutura de fallback, você pode fazer o seguinte:
<AssetTargetFallback Condition=" '$(TargetFramework)'=='netcoreapp3.1' ">
$(AssetTargetFallback);net472;net471
</AssetTargetFallback>
Você pode deixar de lado $(AssetTargetFallback) se desejar substituir, em vez de adicionar aos valores existentes AssetTargetFallback .
Note
Se você estiver usando um projeto baseado no SDK do .NET, os valores apropriados $(AssetTargetFallback) serão configurados e você não precisará defini-los manualmente.
$(PackageTargetFallback) foi um recurso anterior que tentou enfrentar esse desafio, mas está fundamentalmente quebrado e não deve ser usado. Para migrar de para o $(PackageTargetFallback), basta alterar o nome da $(AssetTargetFallback) propriedade.
PrunePackageReference
O .NET Runtime está em constante evolução, com melhorias de desempenho e novas APIs a cada versão.
Novos recursos adicionados ao .NET também são às vezes fornecidos como pacotes, para que os desenvolvedores que usam estruturas de destino mais antigas possam usar a biblioteca, como System.Text.Json.
Muitas vezes, isso pode levar a uma System.Text.Json 8.0.0 segmentação .NET 9 em um projeto ou .NET 8. Essa dependência é desnecessária e a resolução de conflitos de compilação não usaria o assembly proveniente do pacote, uma vez que ele já está disponível no .NET Runtime.
A partir do NuGet versão 6.13 e do .NET SDK 9.0.200, PrunePackageReference permite a remoção desses pacotes no momento da restauração para projetos baseados no SDK do .NET.
A primeira iteração de remoção afetou apenas pacotes transitivos, mas a partir do .NET SDK 10, a remoção de pacotes também afeta pacotes diretos.
A remoção de pacotes está disponível como um recurso de aceitação com o SDK do .NET 9 e é habilitada por padrão para todas as estruturas de um projeto destinado >= .NET 10.0 ao SDK do .NET 10.
A poda de pacotes só está disponível com o resolvedor de dependências padrão, lançado na versão 6.12.
Especificação PrunePackageReference
A lista de pacotes a serem podados é definida com o PrunePackageReference item.
| Attributes | Description |
|---|---|
| Version | Especifica a versão máxima a ser podada.
1.0.0 significa que todos os pacotes até e incluindo 1.0.0 serão removidos. Para 1.0.0, 0.9.0 e 1.0.0 serão podados, mas 1.0.1 não será. |
As propriedades a seguir podem ser usadas para modificar o comportamento de poda.
| PropertyName | Description |
|---|---|
| RestoreEnablePackagePruning | Permite a remoção de pacotes para os pacotes especificados com PrunePackageReference. Esta propriedade é por estrutura de destino e os valores válidos são true e false. Os padrões podem diferir com base no SDK do .NET, conforme definido acima. |
O SDK do .NET predefine a lista de pacotes a serem removidos para você.
Como funciona o PrunePackageReference
Quando um pacote é especificado para ser removido durante a restauração, ele é removido do gráfico de dependência. Quando um pacote é removido, há uma mensagem, visível em detalhes detalhados, indicando que o pacote foi removido para a estrutura de destino dada.
Para pacotes transitivos, ou seja, dependências de outros pacotes ou projetos, os pacotes não são baixados e não aparecem em nenhuma das saídas do NuGet.
Para pacotes diretos, PrivateAssets='all' e IncludeAssets='none' são implicitamente aplicados.
-
IncludeAssets='none'Garante que os assemblies deste pacote não sejam usados durante a compilação. Antes da poda existir, a resolução de conflitos durante a compilação garantia que os assemblies de plataforma fossem preferidos sobre aqueles provenientes dos pacotes. -
PrivateAssets='all'Garante que os pacotes não sejam incluídos em outros pacotes ou por meio de referências de projeto.
Example:
Um projeto como o abaixo:
<PropertyGroup>
<TargetFrameworks>net9.0;netstandard2.0</TargetFrameworks>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="System.Text.Json" Version="9.0.4" />
</ItemGroup>
terá um nuspec com as seguintes dependências:
<dependencies>
<group targetFramework=".NETFramework4.7.2">
<dependency id="System.Text.Json" version="9.0.4" />
</group>
<group targetFramework="net9.0">
</group>
</dependencies>
Quando um PackageReference direto pode ser completamente removido do projeto e um dos frameworks do projeto é .NET 10 ou posterior, NU1510 será gerado solicitando a remoção do pacote. Seguir esta sugestão reduzirá a complexidade do gráfico do seu projeto.
A tabela a seguir resume todos os comportamentos de remoção de pacotes.
| Disposição de dependência | Behavior |
|---|---|
| Corresponde à ID de um pacote transitivo que vem através de outro pacote | Prune |
| Corresponde à ID de um pacote transitivo vindo através de outro projeto | Prune |
Corresponde ao ID de uma conexão direta PackageReference |
Aplique PrivateAssets='all' e IncludeAssets='none' aumente o aviso NU1510 quando o pacote puder ser removido de todas as estruturas e o projeto tiver como destino o .NET 10. |
Corresponde ao ID de um ProjectReference |
Não remova e acione o aviso NU1511 quando o projeto tiver como alvo o .NET 10 |
Aplicativos PrunePackageReference
Os benefícios da poda de embalagens são duplos:
- Benefícios de desempenho, em virtude da redução do número de pacotes dentro de um gráfico de dependência
- Redução de falsos positivos por scanners de componentes, tais como:
NuGetAudit
A poda é particularmente valiosa ao auditar pacotes com NuGetAuditMode definido como all. Se você estiver usando o .NET 9, recomendamos que experimente a remoção definindo RestoreEnablePackagePruning como true.