Pacote e restauração do NuGet como destinos do MSBuild

NuGet 4.0+

Com o formato PackageReference, o NuGet 4.0 e superior pode armazenar todos os metadados de manifesto diretamente dentro de um arquivo de projeto em vez de usar um arquivo .nuspec separado.

Com o MSBuild 15.1 ou superior, o NuGet também é um cidadão de primeira classe do MSBuild com os destinos pack e restore, conforme descrito abaixo. Esses destinos permitem que você trabalhe com o NuGet como faria com qualquer outra tarefa ou destino do MSBuild. Para obter instruções sobre como criar um pacoteNuGet usando o MSBuild, consulte Criar um pacote do NuGet usando o MSBuild. (Para NuGet 3.x e inferiores, use os comandos pack e restore na CLI do NuGet.)

Ordem de build de destino

Como pack e restore são os destinos do MSBuild, você pode acessá-los para melhorar o fluxo de trabalho. Por exemplo, digamos que você deseja copiar o pacote para um compartilhamento de rede após empacotá-lo. Você pode fazer isso adicionando o seguinte ao seu arquivo de projeto:

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

Da mesma forma, você pode gravar uma tarefa do MSBuild escrever seu próprio destino e consumir propriedades do NuGet na tarefa do MSBuild.

pack target

Para projetos .NET que usam o formato PackageReference usando msbuild -t:pack atrai entradas do arquivo de projeto para usar na criação de um pacote NuGet.

A tabela a seguir descreve as propriedades do MSBuild que podem ser adicionadas a um arquivo do projeto dentro do primeiro nó <PropertyGroup>. Você pode fazer essas edições facilmente no Visual Studio 2017 e posterior clicando com o botão direito do mouse no projeto e selecionando Editar {project_name} no menu de contexto. Para sua conveniência, a tabela é organizada pela propriedade equivalente em um arquivo .nuspec.

pack target inputs

pack scenarios

Suprimindo dependências

Para suprimir dependências de pacote do pacote gerado NuGet, defina SuppressDependenciesWhenPacking como true, o qual permitirá ignorar todas as dependências do arquivo nupkg gerado.

PackageIconUrl

PackageIconUrl é preterido em favor da propriedade PackageIcon. A partir da versão 5.3 do NuGet e do Visual Studio 2019 versão 16.3, pack gera o aviso NU5048 se os metadados do pacote especificarem apenas PackageIconUrl.

PackageIcon

Empacotando um arquivo de imagem de ícone

Ao empacotar um arquivo de imagem de ícone, use a propriedade PackageIcon para especificar o caminho do arquivo de ícone, relativo à raiz do pacote. Além disso, certifique-se de que o arquivo está incluído no pacote. O tamanho do arquivo de imagem é limitado a 1 MB. Os formatos de arquivo com suporte incluem JPEG e PNG. Recomendamos uma resolução de imagem de 128x128.

Por exemplo:

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Exemplo de ícone de pacote.

Para o equivalente ao nuspec, dê uma olhada na referência para ícone do nuspec.

PackageReadmeFile

Há suporte com o NuGet 5.10.0 versão prévia 2 / SDK do .NET 5.0.300 e superior

Ao empacotar um arquivo Leiame, você precisa usar a propriedade PackageReadmeFile para especificar o caminho do pacote, relativo à raiz do pacote. Além disso, você precisa certificar-se de que o arquivo está incluído no pacote. Os formatos de arquivo suportados incluem apenas Markdown (.md).

Por exemplo:

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Para o equivalente ao nuspec, dê uma olhada na referência para readme do nuspec.

Assemblies de saída

O nuget pack copia arquivos de saída com extensões .exe, .dll, .xml, .winmd, .json e .pri. Os arquivos de saída que são copiados dependem do que o MSBuild fornece do destino BuiltOutputProjectGroup.

Há duas propriedades de MSBuild que você pode usar em seu arquivo de projeto ou a linha de comando para controlar onde ficam os assemblies de saída:

• IncludeBuildOutput: um valor booliano que determina se os assemblies de saída de build devem ser incluídos no pacote.
• BuildOutputTargetFolder: especifica a pasta na qual os assemblies de saída devem ser colocados. Os assemblies de saída (e outros arquivos de saída) são copiados para suas respectivas pastas de estrutura.

Referências de pacote

Consulte Referências de pacote em arquivos de projeto.

Referências de projeto a projeto

As referências projeto a projeto são consideradas como referências de pacote do NuGet. Por exemplo:

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

Você também pode adicionar os seguintes metadados à referência de projeto:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Incluindo o conteúdo em um pacote

Para incluir o conteúdo, adicione metadados extras ao item <Content> existente. Por padrão, tudo que pertencer ao tipo “Conteúdo” é incluído no pacote, a menos que seja substituído por entradas como a seguinte:

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

Por padrão, tudo é adicionado à raiz da pasta content e contentFiles\any\<target_framework> dentro de um pacote e preserva a estrutura e pasta relativa, a menos que você especifique um caminho de pacote:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

Se você quiser copiar todo o conteúdo somente para determinadas pastas raiz (em vez de para content e contentFiles), será possível usar a propriedade MSBuild do ContentTargetFolders, que assume como padrão "content;contentFiles", mas pode ser definida como qualquer outro nome de pasta. Observe que só especificar “contentFiles” em ContentTargetFolders coloca os arquivos em contentFiles\any\<target_framework> ou contentFiles\<language>\<target_framework> com base em buildAction.

PackagePath pode ser um conjunto de caminhos de destino separados por ponto e vírgula. Especificar um caminho de pacote vazio adicionaria o arquivo à raiz do pacote. Por exemplo, o seguinte adiciona libuv.txt a content\myfiles, content\samples e a raiz do pacote:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

Há também uma propriedade do MSBuild, $(IncludeContentInPack), que assume o padrão true. Se isso for definido como false em qualquer projeto, o conteúdo desse projeto não está incluído no pacote do nuget.

Outros metadados específicos do pacote que pode ser definido em qualquer um dos itens acima <PackageCopyToOutput> e <PackageFlatten>, que define os valores CopyToOutput e Flatten na entrada contentFiles no nuspec de saída.

IncludeSymbols

Ao usar o MSBuild -t:pack -p:IncludeSymbols=true, os arquivos .pdb correspondentes são copiados junto com outros arquivos de saída (.dll, .exe, .winmd, .xml, .json, .pri). Observe que a configuração IncludeSymbols=true cria um pacote regular e um pacote de símbolos.

IncludeSource

Isso é o mesmo que IncludeSymbols, exceto que também copia os arquivos de origem com arquivos .pdb. Todos os arquivos do tipo Compile são copiadas para src\<ProjectName>\, preservando a estrutura de pastas do caminho relativo no pacote resultante. O mesmo também ocorre para arquivos de origem de qualquer ProjectReference que tem TreatAsPackageReference definido como false.

Se um arquivo do tipo Compilação estiver fora da pasta de projeto, ele será adicionado apenas a src\<ProjectName>\.

Empacotando uma expressão de licença ou um arquivo de licença

Ao usar uma expressão de licença, use a propriedade PackageLicenseExpression. Para obter um exemplo, consulte Exemplo de expressão de licença.

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

Para saber mais sobre expressões de licença e licenças aceitas pelo NuGet.org, consulte metadados de licença.

Ao empacotar um arquivo de licença, use a propriedade PackageLicenseFile para especificar o caminho do pacote, relativo à raiz do pacote. Além disso, certifique-se de que o arquivo está incluído no pacote. Por exemplo:

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

Para obter um exemplo, consulte Exemplo de arquivo de licença.

Empacotando um arquivo sem uma extensão

Em alguns cenários, como ao empacotar um arquivo de licença, convém incluir um arquivo sem uma extensão. Por razões históricas, o NuGet e o MSBuild tratam caminhos sem extensão como diretórios.

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>  

Arquivo sem exemplo de extensão.

IsTool

Ao usar MSBuild -t:pack -p:IsTool=true, todos os arquivos de saída, conforme especificado no cenário Assemblies de saída, são copiados para a pasta tools em vez da pasta lib. Observe que isso é diferente de um DotNetCliTool que é especificado pela configuração do PackageType no arquivo .csproj.

Empacotando usando um arquivo .nuspec

Embora seja recomendável incluir todas as propriedades que geralmente estão no arquivo .nuspec no arquivo de projeto, você pode optar por usar um arquivo .nuspec para empacotar seu projeto. Para um projeto que não seja de estilo SDK que usa PackageReference, você deve importar NuGet.Build.Tasks.Pack.targets para que a tarefa do pacote possa ser executada. Você ainda precisa restaurar o projeto antes de empacotar um arquivo nuspec. (Um projeto no estilo SDK inclui os destinos do pacote por padrão.)

A estrutura de destino do arquivo de projeto é irrelevante e não é usada ao empacotar um arquivo do nuspec. As três propriedades MSBuild a seguir são relevantes para empacotamento usando um .nuspec:

1. NuspecFile: caminho relativo ou absoluto para o arquivo .nuspec que está sendo usado para o empacotamento.
2. NuspecProperties: uma lista separada por ponto e vírgula de pares chave/valor. Devido à maneira como a análise de linha de comando do MSBuild funciona, várias propriedades precisam ser especificadas da seguinte maneira: -p:NuspecProperties="key1=value1;key2=value2".
3. NuspecBasePath: o caminho base para o arquivo .nuspec.

Se estiver usando dotnet.exe para empacotar seu projeto, use um comando como o seguinte:

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

Se estiver usando MSBuild para empacotar seu projeto, use um comando como o seguinte:

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

Observe que empacotar um nuspec usando dotnet.exe ou o msbuild também leva à compilação do projeto por padrão. Isso pode ser evitado passando a propriedade --no-build para dotnet.exe, que é o equivalente à configuração <NoBuild>true</NoBuild> no arquivo de projeto, juntamente com a configuração <IncludeBuildOutput>false</IncludeBuildOutput> no arquivo de projeto.

Um exemplo de um arquivo .csproj para empacotar um arquivo nuspec é:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

Pontos de extensão avançados para criar um pacote personalizado

O destino pack fornece dois pontos de extensão que são executados na compilação interna específica da estrutura de destino. Os pontos de extensão oferecem suporte à inclusão de conteúdo específico da estrutura de destino e dos assemblies em um pacote:

• Destino TargetsForTfmSpecificBuildOutput: use para arquivos dentro da pasta lib ou de uma pasta especificada usando BuildOutputTargetFolder.
• Destino TargetsForTfmSpecificContentInPackage: use para arquivos fora do BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Escreva um destino personalizado e especifique-o como o valor da propriedade $(TargetsForTfmSpecificBuildOutput). Para todos os arquivos que precisam ir para BuildOutputTargetFolder (biblioteca por padrão), o destino deve gravar esses arquivos no BuildOutputInPackage do ItemGroup e definir os dois valores de metadados a seguir:

• FinalOutputPath: o caminho absoluto do arquivo. Se não for fornecido, a Identidade será usada para avaliar o caminho de origem.
• TargetPath: (opcional) defina quando o arquivo precisa ir para uma subpasta dentro do lib\<TargetFramework>, como assemblies satélite que vão para suas respectivas pastas de cultura. Usa o nome do arquivo como padrão.

Exemplo:

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

TargetsForTfmSpecificContentInPackage

Escreva um destino personalizado e especifique-o como o valor da propriedade $(TargetsForTfmSpecificContentInPackage). Para que todos os arquivos sejam incluídos no pacote, o destino deve gravar esses arquivos no TfmSpecificPackageFile do ItemGroup e definir os seguintes metadados opcionais:

• PackagePath: caminho onde o arquivo deve ser gerado no pacote. O NuGet emite um aviso se mais de um arquivo for adicionado ao mesmo caminho de pacote.
• BuildAction: a ação de compilação a ser atribuída ao arquivo, necessária somente se o caminho do pacote estiver na pasta contentFiles. Assume o valor padrão “Nenhum”.

Por exemplo,

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>  

restore target

MSBuild -t:restore (que nuget restore e dotnet restore usam com projetos do .NET Core), restaura pacotes referenciados no arquivo de projeto da seguinte maneira:

1. Ler todas as referências projeto a projeto
2. Ler as propriedades do projeto para localizar a pasta intermediária e as estruturas de destino
3. Passe dados do MSBuild para NuGet.Build.Tasks.dll
4. Executar restauração
5. Baixar os pacotes
6. Gravar arquivo de ativos, destinos e objetos

O destino restore funciona para projetos usando o formato PackageReference. MSBuild 16.5+ também tem suporte de aceitação para o formato packages.config.

Restaurar propriedades

Configurações de restauração adicionais podem vir de propriedades do MSBuild no arquivo de projeto. Os valores também podem ser definidos na linha de comando usando a opção -p: (consulte os Exemplos abaixo).

A propriedade ExcludeRestorePackageImports é uma propriedade interna usada pelo NuGet. Não deve ser modificado ou definido em nenhum arquivo do MSBuild.

Exemplos

Linha de comando:

msbuild -t:restore -p:RestoreConfigFile=<path>

Arquivo de projeto:

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

Restaurar saídas

A restauração cria os seguintes arquivos na pasta obj de build:

Restaurando e compilando com um comando do MSBuild

Devido ao fato de que NuGet pode restaurar pacotes que derrubam destinos e adereços do MSBuild, as avaliações de restauração e compilação são executadas com propriedades globais diferentes. Isso significa que os seguintes terão um comportamento imprevisível e, muitas vezes, incorreto.

msbuild -t:restore,build

Em vez disso, a abordagem recomendada é:

msbuild -t:build -restore

A mesma lógica se aplica a outros alvos semelhantes a build.

Restaurando projetos PackageReference e packages.config com o MSBuild

Com o MSBuild 16.5+, também há suporte de packages.config para msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Restauração com avaliação estática de gráficos do MSBuild

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Como alternativa, você pode habilitá-la configurando a propriedade em um arquivo Directory.Build.Props.

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

A restauração estática do gráfico altera a parte msbuild da restauração, a leitura e a avaliação do projeto, mas não o algoritmo de restauração. O algoritmo de restauração é o mesmo em todas as ferramentas do NuGet (NuGet.exe, MSBuild.exe, dotnet.exe e Visual Studio).

Em pouquíssimos cenários, a restauração de gráfico estático pode se comportar de forma diferente da restauração atual e certos PackageReferences ou ProjectReferences declarados podem estar ausentes.

Para tranquilizar sua mente, como uma verificação única, ao migrar para a restauração de gráfico estático, considere executar:

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

O NuGet não deve relatar alterações. Se você vir uma discrepância, registre um problema em NuGet/Home.

Substituindo uma biblioteca de um grafo de restauração

Se uma restauração está trazendo o assembly errado, é possível excluir a escolha padrão do pacote e substituí-lo por outro de sua escolha. Primeiro com um PackageReference de nível superior, exclua todos os ativos:

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

Em seguida, adicione sua própria referência à cópia local apropriada da DLL:

<Reference Include="Newtonsoft.Json.dll" />