NuGet embalar e restaurar como MSBuild alvos

NuGet 4.0+

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

Com MSBuild 15,1+, NuGet é também um cidadão de primeira classe MSBuild com os pack e restore alvos descritos abaixo. Esses objetivos permitem trabalhar com NuGet da mesma forma que com qualquer outra MSBuild tarefa ou meta. Para obter instruções sobre como criar um NuGet pacote usando MSBuild, consulte Criar um NuGet pacote usando MSBuild. (Para NuGet 3.x e anteriores, você usa os comandos pack e restore por meio da CLI.)NuGet

Ordem de construção alvo

Porque pack e restore são MSBuild alvos, você pode acessá-los para melhorar seu fluxo de trabalho. Por exemplo, digamos que você queira copiar seu pacote para um compartilhamento de rede depois de empacotá-lo. Você pode fazer isso adicionando o seguinte em seu arquivo de projeto:

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

Da mesma forma, pode escrever uma tarefa MSBuild, definir o seu próprio alvo e consumir propriedades NuGet na tarefa MSBuild.

Alvo da embalagem

Para projetos .NET que usam o formato PackageReference, utilizar msbuild -t:pack extrai entradas do arquivo de projeto para criar um pacote NuGet.

Projetos sem estilo SDK precisarão instalar o pacote NuGet.Build.Tasks.Pack ao usar o Visual Studio 2022 ou anteriores. Recomendamos desinstalar este pacote ao atualizar para o Visual Studio 2026 para garantir que seu projeto possa usar os recursos de pacote mais recentes e correções de bugs.

A tabela seguinte descreve as MSBuild propriedades que podem ser adicionadas a um ficheiro de 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. Por conveniência, a tabela é organizada pela propriedade equivalente em um .nuspec arquivo.

Agrupar entradas de destino

Cenários agrupados

Supressão de dependências

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

PackageIconUrl

PackageIconUrl está obsoleto em favor da propriedade PackageIcon. A partir da NuGet versão 5.3 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 ficheiro de imagem está limitado a 1 MB. Os formatos de ficheiro suportados 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 nuspec equivalente, dê uma olhada na nuspec referência para o ícone.

PackageReadmeFile

Suportado por NuGet 5.10.0 preview 2 / .NET SDK 5.0.300 e superiores

Ao empacotar um arquivo readme, você precisa usar a PackageReadmeFile propriedade para especificar o caminho do pacote, relativo à raiz do pacote. Além disso, você precisa se certificar de que o arquivo está incluído no pacote. Os formatos de ficheiro 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 nuspec equivalente, dê uma olhada na nuspec referência para o readme.

Montagens de saída

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

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

• IncludeBuildOutput: Um booleano que determina se os assemblies de saída de compilação devem ser incluídos no pacote.
• BuildOutputTargetFolder: Especifica a pasta na qual os assemblies de saída devem ser colocados. Os componentes de saída (e outros ficheiros de saída) são copiados para as respetivas pastas de framework.

Referências de pacotes

Consulte Referências de pacote em arquivos de projeto.

Referências de projeto a projeto

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

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

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

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Incluindo conteúdo em um pacote

Para incluir conteúdo, adicione metadados extras ao item existente <Content> . Por padrão, tudo do tipo "Conteúdo" é incluído no pacote, a menos que você substitua por entradas como as seguintes:

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

Por padrão, tudo é adicionado à raiz das pastas content e contentFiles\any\<target_framework> dentro de um pacote e preserva a estrutura de pastas relativa, a menos que especifique um caminho do pacote.

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

Se desejar copiar todo o conteúdo para apenas uma pasta raiz específica (em vez de content e contentFiles), pode usar a propriedade MSBuild, que tem como valor padrão ContentTargetFolders "conteúdo;contentFiles", mas pode ser configurada para qualquer outro nome de pasta. Observe que apenas especificar "contentFiles" em ContentTargetFolders coloca arquivos sob contentFiles\any\<target_framework> ou contentFiles\<language>\<target_framework> com base em buildAction.

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

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

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

Outros metadados específicos do pacote, que você pode definir em qualquer um dos itens acima, incluem <PackageCopyToOutput> e <PackageFlatten>, que definem os valores de CopyToOutput e Flatten na entrada contentFiles na saída nuspec.

IncluirSímbolos

Ao usar MSBuild -t:pack -p:IncludeSymbols=trueo , os arquivos correspondentes .pdb 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.

IncluirFonte

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

Se um arquivo do tipo Compilar, estiver fora da pasta do projeto, ele será apenas adicionado ao 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 PackageLicenseExpression propriedade. 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 ficheiro de licença, utilize a propriedade PackageLicenseFile para especificar o caminho do ficheiro, 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, talvez você queira incluir um arquivo sem uma extensão. Por razões históricas, NuGet e 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 uma amostra de extensão.

IsTool

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

Empacotando usando um .nuspec ficheiro

Embora seja recomendável que você inclua todas as propriedades que geralmente estão no .nuspec arquivo no arquivo de projeto, você pode optar por usar um .nuspec arquivo para empacotar seu projeto. Você ainda precisa restaurar o projeto antes de poder empacotar um nuspec arquivo. (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 nuspecarquivo . As três MSBuild propriedades a seguir são relevantes para a embalagem usando um .nuspec:

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

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> 

Por favor, note que empacotar um nuspec usando dotnet.exe ou msbuild também leva à construção do projeto por padrão. Isso pode ser evitado passando a propriedade --no-build para dotnet.exe, o que é equivalente a definir <NoBuild>true</NoBuild> no arquivo de projeto, e definir <IncludeBuildOutput>false</IncludeBuildOutput> no mesmo arquivo.

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

<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 pack destino fornece dois pontos de extensão que são executados na compilação interna específica para o framework de destino. Os pontos de extensão oferecem suporte à inclusão de conteúdo e assemblies específicos da estrutura-alvo em um pacote.

• TargetsForTfmSpecificBuildOutput target: Use para arquivos dentro da lib pasta ou de uma pasta especificada usando BuildOutputTargetFolder.
• TargetsForTfmSpecificContentInPackage target: Utilize para ficheiros 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 o BuildOutputTargetFolder (lib por padrão), o destino deve gravar esses arquivos no ItemGroup BuildOutputInPackage e definir os seguintes dois valores de metadados:

• FinalOutputPath: O caminho absoluto do arquivo; se não for fornecida, a Identidade será usada para avaliar o caminho de origem.
• TargetPath: (Opcional) Defina quando o ficheiro precisa ir para uma subpasta dentro do lib\<TargetFramework>, como assemblies satélite que vão para as suas respetivas pastas de cultura. O padrão é o nome do arquivo.

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 quaisquer arquivos a serem incluídos no pacote, o destino deve gravar esses arquivos no ItemGroup TfmSpecificPackageFile e definir os seguintes metadados opcionais:

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

Um 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>  

Restaurar ponto de destino

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

1. Ler todas as referências de projeto para projeto
2. Leia as propriedades do projeto para localizar a pasta intermediária e as estruturas de destino
3. Passar MSBuild dados para NuGet.Build.Tasks.dll
4. Executar restauração
5. Download de pacotes
6. Gravar arquivos de ativos, alvos e propriedades

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

Restaurar propriedades

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

A ExcludeRestorePackageImports propriedade é uma propriedade interna usada por NuGet. Ele não deve ser modificado ou definido em nenhum MSBuild arquivo.

Examples

Linha de comando:

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

Ficheiro do projeto:

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

Restaurar saídas

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

Restaurando e construindo com um MSBuild comando

Devido ao fato de que NuGet pode restaurar pacotes que derrubam MSBuild alvos e props, as avaliações de restauração e compilação são executadas com diferentes propriedades globais. 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 ao build.

Restaurando projetos PackageReference e packages.config com MSBuild

Com MSBuild 16.5+, packages.config também são suportados para msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Restaurando com MSBuild avaliação de gráfico estático

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Como alternativa, você pode habilitá-lo definindo a propriedade em um Directory.Build.Props.

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

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

Em poucos 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 faltando.

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

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

Substituir uma biblioteca de um gráfico de recuperação

Se uma restauração estiver trazendo o assembly errado, é possível excluir a opção padrão do pacote e substituí-la pela sua própria escolha. Primeiro com um nível PackageReferencesuperior, 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" />