NuGet empacotar e restaurar como MSBuild destinos
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 o e restore
os pack
destinos, conforme descrito abaixo. Esses destinos permitem que você trabalhe como NuGet faria com qualquer outra MSBuild tarefa ou destino. 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 o pacote e restaura comandos por meio da NuGet CLI em vez disso.)
Ordem de build de destino
Como pack
e restore
são MSBuild destinos, você pode acessá-los para aprimorar o 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 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 escrever uma MSBuild tarefa, escrever seu próprio destino e consumir NuGet propriedades na MSBuild tarefa.
Observação
$(OutputPath)
é relativo e espera que você esteja executando o comando da raiz do projeto.
pack target
Para projetos do .NET que usam o PackageReference
formato, o uso msbuild -t:pack
desenha entradas do arquivo de projeto a serem usadas na criação de um NuGet pacote.
A tabela a seguir descreve as MSBuild propriedades que podem ser adicionadas a um arquivo de projeto no primeiro <PropertyGroup>
nó. 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 conveniência, a tabela é organizada pela propriedade equivalente em um .nuspec
arquivo.
Observação
Owners
e Summary
propriedades de .nuspec
não têm suporte com MSBuild.
Atributo/nuspec valor | MSBuild Propriedade | Padrão | Observações |
---|---|---|---|
Id |
PackageId |
$(AssemblyName) |
$(AssemblyName) de MSBuild |
Version |
PackageVersion |
Versão | Isso é compatível com semver, por exemplo 1.0.0 , 1.0.0-beta ou 1.0.0-beta-00345 . O padrão é definir Version se não for definido. |
VersionPrefix |
VersionPrefix |
empty | Definindo PackageVersion substituições VersionPrefix |
VersionSuffix |
VersionSuffix |
empty | Definindo PackageVersion substituições VersionSuffix |
Authors |
Authors |
Nome do usuário atual | Uma lista separada por ponto e vírgula de autores de pacotes, que corresponde aos nomes de perfil em nuget.org. Elas são exibidas na NuGet Galeria no nuget.org e são usadas para fazer referência cruzada a pacotes pelos mesmos autores. |
Owners |
N/D | Não presente em nuspec | |
Title |
Title |
$(PackageId) |
Um título amigável do pacote, geralmente usado em exibições de interface do usuário como em nuget.org e no Gerenciador de Pacotes do Visual Studio. |
Description |
Description |
“Package Description” | Uma descrição longa para o manifesto do assembly. Se PackageDescription não for especificado, essa propriedade também será usada como a descrição do pacote. |
Copyright |
Copyright |
empty | Detalhes sobre direitos autorais do pacote. |
RequireLicenseAcceptance |
PackageRequireLicenseAcceptance |
false |
Um valor booliano que especifica se o cliente deve solicitar que o consumidor aceite a licença do pacote antes de instalá-lo. |
license |
PackageLicenseExpression |
empty | Corresponde ao <license type="expression"> . Consulte Empacotando uma expressão de licença ou um arquivo de licença. |
license |
PackageLicenseFile |
empty | Caminho para um arquivo de licença dentro do pacote se você estiver usando uma licença personalizada ou uma licença que não tenha sido atribuída a um identificador SPDX. Você precisa empacotar explicitamente o arquivo de licença referenciado. Corresponde ao <license type="file"> . Consulte Empacotando uma expressão de licença ou um arquivo de licença. |
LicenseUrl |
PackageLicenseUrl |
empty | O PackageLicenseUrl foi preterido. Use PackageLicenseExpression ou PackageLicenseFile em vez disso. |
ProjectUrl |
PackageProjectUrl |
empty | |
Icon |
PackageIcon |
empty | Um caminho para uma imagem no pacote a ser usado como um ícone de pacote. Você precisa empacotar explicitamente o arquivo de imagem de ícone referenciado. Para obter mais informações, consulte Empacotando um arquivo de imagem de ícone e icon metadados. |
IconUrl |
PackageIconUrl |
empty | PackageIconUrl é preterido em favor de PackageIcon . No entanto, para obter a melhor experiência de nível inferior, você deve especificar PackageIconUrl além de PackageIcon . |
Readme |
PackageReadmeFile |
empty | Você precisa empacotar explicitamente o arquivo readme referenciado. |
Tags |
PackageTags |
empty | Uma lista delimitada por ponto e vírgula de marcas que designam o pacote. |
ReleaseNotes |
PackageReleaseNotes |
empty | Notas de versão do projeto. |
Repository/Url |
RepositoryUrl |
empty | URL do repositório usada para clonar ou recuperar o código-fonte. Exemplo: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git. |
Repository/Type |
RepositoryType |
empty | Tipo de repositório. Exemplos: git (padrão), tfs . |
Repository/Branch |
RepositoryBranch |
empty | Informações opcionais do branch do repositório. RepositoryUrl também deve ser especificado para que essa propriedade seja incluída. Exemplo: mestre (NuGet 4.7.0+). |
Repository/Commit |
RepositoryCommit |
empty | Confirmação de repositório opcional ou conjunto de alterações para indicar em qual origem o pacote foi criado. RepositoryUrl também deve ser especificado para que essa propriedade seja incluída. Exemplo: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+). |
PackageType |
<PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> |
Indica o uso pretendido do pacote. Os tipos de pacote usam o mesmo formato que as IDs do pacote e são delimitados por ; . Os tipos de pacote podem ser versão acrescentando uma e uma , cadeia de Version caracteres. Consulte Definir um NuGet tipo de pacote (NuGet 3.5.0+). |
|
Summary |
Sem suporte |
pack target inputs
Propriedade | Descrição |
---|---|
IsPackable |
Um valor booliano que especifica se o projeto pode ser empacotado. O valor padrão é true . |
SuppressDependenciesWhenPacking |
Defina para true suprimir as dependências do pacote gerado NuGet . |
PackageVersion |
Especifica a versão que o pacote resultante terá. Aceita todas as formas de cadeia de caracteres de NuGet versão. O padrão é o valor $(Version) , ou seja, da propriedade Version no projeto. |
PackageId |
Especifica o nome para o pacote resultante. Se não for especificado, a operação pack usará como padrão o AssemblyName ou o nome do diretório como o nome do pacote. |
PackageDescription |
Uma descrição longa do pacote para exibição de interface do usuário. |
Authors |
Uma lista separada por ponto e vírgula de autores de pacotes, que corresponde aos nomes de perfil em nuget.org. Elas são exibidas na NuGet Galeria no nuget.org e são usadas para fazer referência cruzada a pacotes pelos mesmos autores. |
Description |
Uma descrição longa para o manifesto do assembly. Se PackageDescription não for especificado, essa propriedade também será usada como a descrição do pacote. |
Copyright |
Detalhes sobre direitos autorais do pacote. |
PackageRequireLicenseAcceptance |
Um valor booliano que especifica se o cliente deve solicitar que o consumidor aceite a licença do pacote antes de instalá-lo. O padrão é false . |
DevelopmentDependency |
Um valor booliano que especifica se o pacote é marcado 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 os ativos de tempo de compilação são excluídos da compilação. Para obter mais informações, confira Suporte do DevelopmentDependency para PackageReference. |
PackageLicenseExpression |
Um identificador ou expressão de licença SPDX , por exemplo, Apache-2.0 . Para obter mais informações, consulte Empacotando uma expressão de licença ou um arquivo de licença. |
PackageLicenseFile |
Caminho para um arquivo de licença dentro do pacote se você estiver usando uma licença personalizada ou uma licença que não tenha sido atribuída a um identificador SPDX. |
PackageLicenseUrl |
O PackageLicenseUrl foi preterido. Use PackageLicenseExpression ou PackageLicenseFile em vez disso. |
PackageProjectUrl |
|
PackageIcon |
Especifica o caminho do ícone do pacote em relação à raiz do pacote. Para obter mais informações, consulte Empacotando um arquivo de imagem de ícone. |
PackageReleaseNotes |
Notas de versão do projeto. |
PackageReadmeFile |
Leiame para o pacote. |
PackageTags |
Uma lista delimitada por ponto e vírgula de marcas que designam o pacote. |
PackageOutputPath |
Determina o caminho de saída no qual o pacote empacotado será solto. O padrão é $(OutputPath) . |
IncludeSymbols |
Esse valor booliano indica se o pacote deve criar um pacote de símbolos adicionais quando o projeto é empacotado. O formato do pacote de símbolos é controlado pela propriedade SymbolPackageFormat . Para obter mais informações, consulte IncludeSymbols. |
IncludeSource |
Esse valor booliano indica se o processo do pacote deve criar um pacote de origem. O pacote de origem contém o código-fonte da biblioteca, bem como arquivos PDB. Os arquivos de origem são colocados no diretório src/ProjectName , no arquivo de pacote resultante. Para obter mais informações, consulte IncludeSource. |
PackageType |
|
IsTool |
Especifica se todos os arquivos de saída são copiados para a pasta tools em vez da pasta lib. Para obter mais informações, consulte IsTool. |
RepositoryUrl |
URL do repositório usada para clonar ou recuperar o código-fonte. Exemplo: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git. |
RepositoryType |
Tipo de repositório. Exemplos: git (padrão), tfs . |
RepositoryBranch |
Informações opcionais do branch do repositório. RepositoryUrl também deve ser especificado para que essa propriedade seja incluída. Exemplo: mestre (NuGet 4.7.0+). |
RepositoryCommit |
Confirmação de repositório opcional ou conjunto de alterações para indicar em qual origem o pacote foi criado. RepositoryUrl também deve ser especificado para que essa propriedade seja incluída. Exemplo: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+). |
SymbolPackageFormat |
Especifica o formato do pacote de símbolos. Se "symbols.nupkg", um pacote de símbolos herdados é criado com uma extensão .symbols.nupkg contendo PDBs, DLLs e outros arquivos de saída. Se "snupkg", um pacote de símbolo de snupkg será criado contendo os PDBs portáteis. O padrão é "symbols.nupkg". |
NoPackageAnalysis |
Especifica que pack não deve executar a análise de pacote após a criação do pacote. |
MinClientVersion |
Especifica a versão mínima do NuGet cliente que pode instalar esse pacote, imposta pelo nuget.exe e pelo Visual Studio Gerenciador de Pacotes. |
IncludeBuildOutput |
Esse valor booliano especifica se os assemblies de saída de build devem ser empacotados no arquivo .nupkg ou não. |
IncludeContentInPack |
Esse valor booliano especifica se todos os itens que têm um tipo de Content são incluídos no pacote resultante automaticamente. O padrão é true . |
BuildOutputTargetFolder |
Especifica a pasta para colocar os assemblies de saída. Os assemblies de saída (e outros arquivos de saída) são copiados para suas respectivas pastas de estrutura. Para obter mais informações, consulte assemblies de saída. |
ContentTargetFolders |
Especifica o local padrão de onde todos os arquivos de conteúdo devem ir se PackagePath não for especificado para eles. O valor padrão é “content;contentFiles”. Para obter mais informações, consulte Incluindo conteúdo em um pacote. |
NuspecFile |
Caminho relativo ou absoluto para o .nuspec arquivo que está sendo usado para empacotamento. Se especificado, ele é usado exclusivamente para informações de empacotamento e qualquer informação nos projetos não é usada. Para obter mais informações, consulte Empacotar usando um .nuspec. |
NuspecBasePath |
Caminho base para o .nuspec arquivo. Para obter mais informações, consulte Empacotar usando um .nuspec. |
NuspecProperties |
Lista separada por ponto e vírgula de pares chave-valor. Para obter mais informações, consulte Empacotar usando um .nuspec. |
pack scenarios
Suprimindo dependências
Para suprimir dependências de pacote do pacote gerado NuGet , defina SuppressDependenciesWhenPacking
para o true
qual permitirá ignorar todas as dependências do arquivo nupkg gerado.
PackageIconUrl
PackageIconUrl
é preterido em favor da PackageIcon
propriedade. Começando com NuGet 5.3 e Visual Studio versão 16.3 de 2019, pack
gera o aviso NU5048 se os metadados do pacote especificarem PackageIconUrl
apenas .
PackageIcon
Dica
Para manter a compatibilidade com versões anteriores com clientes e fontes que ainda não dão suporte PackageIcon
, especifique ambos PackageIcon
e PackageIconUrl
. Visual Studio dá suporte a pacotes provenientes PackageIcon
de uma fonte baseada em pasta.
Empacotando um arquivo de imagem de ícone
Ao empacotar um arquivo de imagem de ícone, use PackageIcon
a propriedade para especificar o caminho do arquivo de ícone, em relação à raiz do pacote. Além disso, verifique se 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>
Para o nuspec equivalente, dê uma olhada na nuspec referência do ícone.
PackageReadmeFile
Com suporte com NuGet o SDK 5.10.0 versão prévia 2.NET / 5.0.300 e superior
Ao empacotar um arquivo readme, você precisa usar a PackageReadmeFile
propriedade para especificar o caminho do pacote, em relação à raiz do pacote. Além disso, você precisa verificar se o arquivo está incluído no pacote. Os formatos de arquivo com suporte 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 de readme.
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 copiados dependem do 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 vão 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
Project para referências de 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 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 para apenas uma(s) pasta(s) raiz específica (em vez de content
ambas contentFiles
), poderá usar a MSBuild propriedade ContentTargetFolders
, que usa 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 MSBuild propriedade $(IncludeContentInPack)
, que usa como padrão true
. Se isso for definido como false
em qualquer projeto, o conteúdo desse projeto não está incluso no pacote do nuget.
Outros metadados específicos do pacote que você pode definir em qualquer um dos itens acima incluem e quais conjuntos CopyToOutput
e Flatten
valores na contentFiles
entrada na saídanuspec.<PackageFlatten>
<PackageCopyToOutput>
Observação
Além de itens de Conteúdo, os metadados <Pack>
e <PackagePath>
também podem ser definidos em arquivos com uma ação de Compile, EmbeddedResource, ApplicationDefinition, Page, Resource, SplashScreen, DesignData, DesignDataWithDesignTimeCreateableTypes, CodeAnalysisDictionary, AndroidAsset, AndroidResource, BundleResource ou None.
Para o pacote acrescentar o nome de arquivo ao caminho do pacote ao usar padrões glob, seu caminho de pacote deve terminar com o caractere separador de pasta, caso contrário, o caminho do pacote será tratado como o caminho completo, incluindo o nome do arquivo.
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 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 que são aceitas pelo NuGet.org, consulte metadados de licença.
Ao empacotar um arquivo de licença, use PackageLicenseFile
a propriedade para especificar o caminho do pacote, em relação à raiz do pacote. Além disso, verifique se 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.
Observação
Somente um de PackageLicenseExpression
, PackageLicenseFile
e PackageLicenseUrl
pode ser especificado por vez.
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 motivos históricos, NuGet&MSBuild trate caminhos sem uma extensão como diretórios.
<PropertyGroup>
<TargetFrameworks>netstandard2.0</TargetFrameworks>
<PackageLicenseFile>LICENSE</PackageLicenseFile>
</PropertyGroup>
<ItemGroup>
<None Include="LICENSE" Pack="true" PackagePath=""/>
</ItemGroup>
Arquivo sem um 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
.
Empacotamento usando um .nuspec
arquivo
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. Para um projeto não 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 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 nuspec. As três MSBuild propriedades a seguir são relevantes para empacotamento usando um .nuspec
:
NuspecFile
: caminho relativo ou absoluto para o arquivo.nuspec
que está sendo usado para o empacotamento.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"
.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 uso dotnet.exe ou msbuild também leva à criação do projeto por padrão. Isso pode ser evitado passando --no-build
a propriedade para dotnet.exe, que é o equivalente à configuração <NoBuild>true</NoBuild>
em seu arquivo de projeto, juntamente com a configuração <IncludeBuildOutput>false</IncludeBuildOutput>
no arquivo de projeto.
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 no build específico da estrutura interna de destino. Os pontos de extensão dão suporte, incluindo conteúdo específico da estrutura de destino e assemblies em um pacote:
TargetsForTfmSpecificBuildOutput
destino: Usar para arquivos dentro dalib
pasta ou uma pasta especificada usandoBuildOutputTargetFolder
.TargetsForTfmSpecificContentInPackage
destino: Usar para arquivos fora doBuildOutputTargetFolder
.
TargetsForTfmSpecificBuildOutput
Escreva um destino personalizado e especifique-o como o valor da $(TargetsForTfmSpecificBuildOutput)
propriedade. Para todos os arquivos que precisam entrar no BuildOutputTargetFolder
(lib por padrão), o destino deve gravar esses arquivos no ItemGroup BuildOutputInPackage
e definir os dois valores de metadados a seguir:
FinalOutputPath
: o caminho absoluto do arquivo; se não for fornecida, a Identidade será usada para avaliar o caminho de origem.TargetPath
: (Opcional) Definir quando o arquivo precisa entrar em uma subpasta dentrolib\<TargetFramework>
, como assemblies satélites que passam por suas respectivas 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 $(TargetsForTfmSpecificContentInPackage)
propriedade. Para que todos os arquivos incluam no pacote, o destino deve gravar esses arquivos no ItemGroup TfmSpecificPackageFile
e definir os seguintes metadados opcionais:
PackagePath
: caminho em que o arquivo deve ser saída no pacote. NuGet emitirá um aviso se mais de um arquivo for adicionado ao mesmo caminho do pacote.BuildAction
: a ação de build a ser atribuída ao arquivo, necessária somente se o caminho do pacote estiver nacontentFiles
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>
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:
- Ler todas as referências projeto a projeto
- Ler as propriedades do projeto para localizar a pasta intermediária e as estruturas de destino
- Passar MSBuild dados para NuGet.Build.Tasks.dll
- Executar restauração
- Baixar os pacotes
- Gravar arquivo de ativos, destinos e objetos
O restore
destino funciona para projetos usando o formato PackageReference.
MSBuild 16.5+
também tem suporte de aceitação para o packages.config
formato.
Observação
O restore
destino não deve ser executado em combinação com o build
destino.
Restaurar propriedades
As configurações de restauração adicionais podem vir de MSBuild propriedades no arquivo de projeto. Os valores também podem ser definidos na linha de comando usando a opção -p:
(consulte os Exemplos abaixo).
Propriedade | Descrição |
---|---|
RestoreSources |
Uma lista delimitada por ponto e vírgula de origens de pacote. |
RestorePackagesPath |
Caminho da pasta dos pacotes do usuário. |
RestoreDisableParallel |
Limite os downloads para um de cada vez. |
RestoreConfigFile |
Caminho para um arquivo Nuget.Config a ser aplicado. |
RestoreNoCache |
Se for true, evita o uso de pacotes armazenados em cache. Consulte Gerenciar os pacotes globais e as pastas de cache. |
RestoreIgnoreFailedSources |
Se verdadeiro, ignora origens de pacote com falha ou ausentes. |
RestoreFallbackFolders |
Pastas de fallback, usadas da mesma forma que a pasta de pacotes de usuário é usada. |
RestoreAdditionalProjectSources |
Fontes adicionais a serem usadas durante a restauração. |
RestoreAdditionalProjectFallbackFolders |
Pastas de fallback adicionais a serem usadas durante a restauração. |
RestoreAdditionalProjectFallbackFoldersExcludes |
Exclui pastas de fallback especificadas em RestoreAdditionalProjectFallbackFolders |
RestoreTaskAssemblyFile |
Caminho para NuGet.Build.Tasks.dll . |
RestoreGraphProjectInput |
Lista separada por ponto e vírgula de projetos a serem restaurados, que devem conter caminhos absolutos. |
RestoreUseSkipNonexistentTargets |
Quando os projetos são coletados por meio MSBuild dele determina se eles são coletados usando a SkipNonexistentTargets otimização. Quando não definido, o padrão é true . A consequência é um comportamento rápido de fail-fast quando os destinos de um projeto não podem ser importados. |
MSBuildProjectExtensionsPath |
Pasta de saída, padrão para BaseIntermediateOutputPath e a obj pasta. |
RestoreForce |
Em projetos baseados em PackageReference, força que todas as dependências sejam resolvidas mesmo que a última restauração tenha sido bem-sucedida. Especificar esse sinalizador é semelhante à exclusão do project.assets.json arquivo. Isso não ignora o cache http. |
RestorePackagesWithLockFile |
Aceita o uso de um arquivo de bloqueio. |
RestoreLockedMode |
Execute a restauração no modo bloqueado. Isso significa que a restauração não reavaliará as dependências. |
NuGetLockFilePath |
Um local personalizado para o arquivo de bloqueio. O local padrão é ao lado do projeto e é nomeado packages.lock.json . |
RestoreForceEvaluate |
Força a restauração para recompor as dependências e atualizar o arquivo de bloqueio sem nenhum aviso. |
RestorePackagesConfig |
Uma opção de aceitação que restaura projetos com packages.config. Suporte somente com MSBuild -t:restore . |
RestoreRepositoryPath |
packages.config apenas. Especifica o diretório de pacotes ao qual os pacotes devem ser restaurados. SolutionDirectory será usado se não for especificado. |
RestoreUseStaticGraphEvaluation |
Uma opção de aceitação para usar a avaliação de grafo MSBuild estático em vez da avaliação padrão. A avaliação de grafo estático é um recurso experimental que é significativamente mais rápido para grandes repositórios e soluções. |
A ExcludeRestorePackageImports
propriedade é uma propriedade interna usada por NuGet.
Ele não deve ser modificado nem definido em nenhum MSBuild arquivo.
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:
Arquivo | Descrição |
---|---|
project.assets.json |
Contém o grafo de dependência de todas as referências de pacote. |
{projectName}.projectFileExtension.nuget.g.props |
Referências a MSBuild adereços contidos em pacotes |
{projectName}.projectFileExtension.nuget.g.targets |
Referências a MSBuild destinos contidos em pacotes |
Restaurando e criando com um MSBuild comando
Devido ao fato de que NuGet podem restaurar pacotes que derrubam MSBuild destinos e adereços, as avaliações de restauração e compilação são executadas com propriedades globais diferentes. Isso significa que o seguinte terá um comportamento imprevisível e geralmente incorreto.
msbuild -t:restore,build
Em vez disso, a abordagem recomendada é:
msbuild -t:build -restore
A mesma lógica se aplica a outros destinos semelhantes a build
.
Restaurando projetos packageReference e packages.config com MSBuild
Com MSBuild 16,5+, também há suporte para msbuild -t:restore
packages.config .
msbuild -t:restore -p:RestorePackagesConfig=true
Observação
packages.config
a restauração só está disponível com MSBuild 16.5+
, e não com dotnet.exe
Restaurando com MSBuild avaliação de grafo estático
Observação
Com MSBuild 16.6+, NuGet adicionou um recurso experimental para usar a avaliação de grafo estático da linha de comando que melhora significativamente o tempo de restauração para repositórios grandes.
msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true
Como alternativa, você pode habilitá-la definindo a propriedade em um Directory.Build.Props.
<Project>
<PropertyGroup>
<RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
</PropertyGroup>
</Project>
Observação
A partir de Visual Studio 2019.x e NuGet 5.x, esse recurso é considerado experimental e opt-in. Siga NuGet/Home#9803 para obter detalhes sobre quando esse recurso será habilitado por padrão.
A restauração do grafo estático 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 NuGet ferramentas (NuGet.exe, MSBuild.exe, dotnet.exe e Visual Studio).
Em pouquíssimos cenários, a restauração de grafo estático pode se comportar de forma diferente da restauração atual e determinadas PackageReferences declaradas ou ProjectReferences podem estar ausentes.
Para facilitar sua mente, como uma verificação única, ao migrar para a restauração estática do grafo, considere a execução:
msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore
NuGetnão deve relatar nenhuma alteração. 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" />