NuGet упаковка и восстановление в качестве целевых MSBuild объектов

  • Статья

NuGet 4.0+

В формате NuGet PackageReference 4.0+ может хранить все метаданные манифеста непосредственно в файле проекта, а не использовать отдельный .nuspec файл.

С MSBuild 15.1+, NuGet также является гражданином первого класса MSBuild с и restore целевыми pack объектами, как описано ниже. Эти целевые объекты позволяют работать с NuGet другими MSBuild задачами или целевыми объектами. Инструкции по созданию NuGet пакета с помощью см. в разделе "Создание NuGet пакета с помощьюMSBuildMSBuild". (для NuGet 3.x и более ранних версий вы используете команды пакета и восстановления с помощью интерфейса командной NuGet строки.)

Порядок сборки целевого объекта

Так как pack и restore являются целевыми MSBuild объектами, вы можете получить доступ к ним для улучшения рабочего процесса. Например, предположим, что вы хотите скопировать пакет в сетевую папку после упаковки. Это можно сделать, добавив следующий код в файл проекта:

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

Аналогичным образом можно написать задачу, написать собственный целевой MSBuild объект и использовать NuGet свойства в MSBuild задаче.

Примечание.

$(OutputPath) является относительным и ожидает, что команда выполняется из корневого каталога проекта.

Целевой объект pack

Для проектов .NET, использующих PackageReference формат, с помощью msbuild -t:pack рисования входных данных из файла проекта для создания NuGet пакета.

В следующей таблице описаны MSBuild свойства, которые можно добавить в файл проекта в первом <PropertyGroup> узле. Эти изменения легко внести в Visual Studio 2017 и более поздней версии, щелкнув проект правой кнопкой мыши и выбрав пункт Изменить {project_name}. Для удобства таблица организована эквивалентным свойством в .nuspec файле.

Примечание.

Owners и Summary свойства из .nuspec них не поддерживаются MSBuild.

Атрибут/nuspec значение СвойствоMSBuild По умолчанию. Примечания.
Id PackageId $(AssemblyName) $(AssemblyName) из MSBuild
Version PackageVersion Версия Это совместимо с semver, например 1.0.01.0.0-beta, или 1.0.0-beta-00345. Значение по умолчанию, Version если оно не задано.
VersionPrefix VersionPrefix empty Настройка PackageVersion перезаписей VersionPrefix
VersionSuffix VersionSuffix empty Настройка PackageVersion перезаписей VersionSuffix
Authors Authors Имя текущего пользователя Список авторов пакетов с запятой, соответствующий именам профилей nuget.org. Они отображаются в коллекции на NuGet nuget.org и используются для перекрестной ссылки на пакеты теми же авторами.
Owners Н/П Не присутствует в nuspec
Title Title $(PackageId) Понятный заголовок пакета, обычно используемый при отображении пользовательского интерфейса, как на сайте nuget.org и в диспетчере пакетов Visual Studio.
Description Description "Описание пакета" Подробное описание сборки. Если PackageDescription не указывать, это свойство также будет использоваться в качестве описания пакета.
Copyright Copyright empty Сведения об авторских правах для пакета.
RequireLicenseAcceptance PackageRequireLicenseAcceptance false Логическое значение, указывающее, должен ли клиент просить потребителя принять условия лицензии перед установкой пакета.
license PackageLicenseExpression empty Соответствует <license type="expression">. См. раздел "Упаковка выражения лицензии" или файла лицензии.
license PackageLicenseFile empty Путь к файлу лицензии в пакете, если вы используете пользовательскую лицензию или лицензию, которая не была назначена идентификатору SPDX. Необходимо явно упаковать указанный файл лицензии. Соответствует <license type="file">. См. раздел "Упаковка выражения лицензии" или файла лицензии.
LicenseUrl PackageLicenseUrl empty PackageLicenseUrl не рекомендуется к использованию. Вместо этого используются типы PackageLicenseExpression или PackageLicenseFile.
ProjectUrl PackageProjectUrl empty
Icon PackageIcon empty Путь к образу в пакете, используемому в качестве значка пакета. Необходимо явно упаковать файл изображения со ссылкой на значок. Дополнительные сведения см. в разделе "Упаковка файла изображения значка" и icon метаданных.
IconUrl PackageIconUrl empty Вместо PackageIconUrl теперь используется PackageIcon. Однако для лучшего опыта понижения необходимо указать PackageIconUrl в дополнение к PackageIcon.
Readme PackageReadmeFile empty Необходимо явно упаковать указанный файл readme.
Tags PackageTags empty Разделенный точками с запятой список тегов, обозначающий пакет.
ReleaseNotes PackageReleaseNotes empty Заметки о выпуске для пакета.
Repository/Url RepositoryUrl empty URL-адрес репозитория, используемый для клонирования или получения исходного кода. Пример: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
Repository/Type RepositoryType empty Тип репозитория. Примеры: git (по умолчанию), tfs.
Repository/Branch RepositoryBranch empty Необязательные сведения о ветви репозитория. Необходимо также указать RepositoryUrl, чтобы включить это свойство. Пример: master (NuGet 4.7.0+).
Repository/Commit RepositoryCommit empty Необязательная фиксация или набор изменений репозитория для указания источника, на основе которого был создан пакет. Необходимо также указать RepositoryUrl, чтобы включить это свойство. Пример: 0e4d1b598f350b3dc675018d53914d1328189ef (NuGet 4.7.0+).
PackageType <PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> Указывает предполагаемое использование пакета. Типы пакетов используют тот же формат, что и идентификаторы пакетов и разделены по разделителям ;. Типы пакетов могут быть версиями путем добавления , строки и строки Version . См. NuGet раздел "Задать тип пакета" (NuGet3.5.0+).
Summary Не поддерживается

Входные данные целевого объекта pack

Свойство Description
IsPackable Логическое значение, которое указывает, можно ли упаковать проект. Значение по умолчанию — true.
SuppressDependenciesWhenPacking Установите для true подавления зависимостей пакета из созданного NuGet пакета.
PackageVersion Указывает версию, которую будет иметь итоговый пакет. Принимает все формы NuGet строки версии. По умолчанию используется значение $(Version), то есть значение свойства Version в проекте.
PackageId Указывает имя для итогового пакета. Если значение не указано, операция pack по умолчанию использует в качестве имени пакета AssemblyName или имя каталога.
PackageDescription Подробное описание пакета для отображения пользовательского интерфейса.
Authors Список авторов пакетов с запятой, соответствующий именам профилей nuget.org. Они отображаются в коллекции на NuGet nuget.org и используются для перекрестной ссылки на пакеты теми же авторами.
Description Подробное описание сборки. Если PackageDescription не указывать, это свойство также будет использоваться в качестве описания пакета.
Copyright Сведения об авторских правах для пакета.
PackageRequireLicenseAcceptance Логическое значение, указывающее, должен ли клиент просить потребителя принять условия лицензии перед установкой пакета. Значение по умолчанию — false.
DevelopmentDependency Логическое значение, указывающее на то, помечен ли пакет как зависимость только для разработки, что позволяет запретить его включение в качестве зависимости в другие пакеты. При использовании PackageReference (NuGet 4.8+) этот флаг также означает, что ресурсы времени компиляции исключены из компиляции. Дополнительные сведения см. в статье DevelopmentDependency support for PackageReference (Поддержка DevelopmentDependency для PackageReference).
PackageLicenseExpression НапримерApache-2.0, идентификатор лицензии или выражение SPDX. Дополнительные сведения см. в статье "Упаковка выражения лицензии" или файла лицензии.
PackageLicenseFile Путь к файлу лицензии в пакете, если вы используете пользовательскую лицензию или лицензию, которая не была назначена идентификатору SPDX.
PackageLicenseUrl PackageLicenseUrl не рекомендуется к использованию. Вместо этого используются типы PackageLicenseExpression или PackageLicenseFile.
PackageProjectUrl
PackageIcon Указывает путь к значку пакета относительно корневого каталога пакета. Дополнительные сведения см. в разделе "Упаковка файла изображения значка".
PackageReleaseNotes Заметки о выпуске для пакета.
PackageReadmeFile Readme для пакета.
PackageTags Разделенный точками с запятой список тегов, обозначающий пакет.
PackageOutputPath Определяет выходной путь для размещения упакованного пакета. По умолчанию — $(OutputPath).
IncludeSymbols Это логическое значение указывает, должен ли пакет создавать дополнительный пакет символов при упаковке проекта. Форматом пакета символов управляет свойство SymbolPackageFormat. Дополнительные сведения см. в разделе IncludeSymbols.
IncludeSource Это логическое значение указывает, должен ли процесс упаковки создавать исходный пакет. Исходный пакет содержит библиотеку исходного кода, а также файлы PDB. Исходные файлы помещаются в каталог src/ProjectName итогового файла пакета. Дополнительные сведения см. в разделе IncludeSource.
PackageType
IsTool Указывает, копируются ли все выходные файлы в папку tools вместо папки lib. Дополнительные сведения см. в разделе IsTool.
RepositoryUrl URL-адрес репозитория, используемый для клонирования или получения исходного кода. Пример: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
RepositoryType Тип репозитория. Примеры: git (по умолчанию), tfs.
RepositoryBranch Необязательные сведения о ветви репозитория. Необходимо также указать RepositoryUrl, чтобы включить это свойство. Пример: master (NuGet 4.7.0+).
RepositoryCommit Необязательная фиксация или набор изменений репозитория для указания источника, на основе которого был создан пакет. Необходимо также указать RepositoryUrl, чтобы включить это свойство. Пример: 0e4d1b598f350b3dc675018d53914d1328189ef (NuGet 4.7.0+).
SymbolPackageFormat Задает формат пакета символов. Если "symbols.nupkg", то пакет устаревших символов создается с расширением .symbols.nupkg , содержащим PDF-файлы, библиотеки DLL и другие выходные файлы. Если "snupkg", создается пакет символов snupkg, содержащий переносимые PDF-файлы. Значение по умолчанию — symbols.nupkg.
NoPackageAnalysis Указывает, что pack не следует выполнять анализ пакетов после сборки пакета.
MinClientVersion Указывает минимальную версию NuGet клиента, которая может установить этот пакет, примененную nuget.exe и диспетчер пакетов Visual Studio.
IncludeBuildOutput Это логическое значение указывает, следует ли упаковывать выходные сборки в файл NUPKG.
IncludeContentInPack Это логическое значение указывает, включены ли все элементы, имеющие тип Content , в результирующий пакет автоматически. Значение по умолчанию — true.
BuildOutputTargetFolder Указывает папку для размещения выходных сборок. Выходные сборки (и другие выходные файлы) копируются в соответствующие папки платформы. Дополнительные сведения см. в разделе "Выходные сборки".
ContentTargetFolders Указывает расположение по умолчанию, в котором должны находиться все файлы содержимого, если PackagePath для них не указано. Значение по умолчанию — "content;contentFiles". Дополнительные сведения см. в статье Включение содержимого в пакет.
NuspecFile Относительный или абсолютный путь к файлу, используемому .nuspec для упаковки. Если он указан, он используется исключительно для упаковки информации, а любые сведения в проектах не используются. Дополнительные сведения см. в разделе "Упаковка с помощью"..nuspec
NuspecBasePath Базовый путь к файлу .nuspec . Дополнительные сведения см. в разделе "Упаковка с помощью"..nuspec
NuspecProperties Список разделенных точками с запятой пар "ключ-значение". Дополнительные сведения см. в разделе "Упаковка с помощью"..nuspec

Сценарии использования pack

Подавление зависимостей

Чтобы отключить зависимости пакета из созданного NuGet пакета, задайте для SuppressDependenciesWhenPackingtrue этого значение, которое позволит пропускать все зависимости из созданного файла nupkg.

PackageIconUrl

PackageIconUrl не рекомендуется использовать PackageIcon свойство. Начиная с NuGet версии 5.3 и Visual Studio 2019 версии 16.3, возникает предупреждение NU5048, pack если метаданные пакета указывают PackageIconUrlтолько.

PackageIcon

Совет

Чтобы обеспечить обратную совместимость с клиентами и источниками, которые еще не поддерживаются PackageIcon, укажите оба PackageIcon и PackageIconUrl. Visual Studio поддерживает PackageIcon пакеты, поступающие из источника на основе папок.

Упаковка файла изображения значка

При упаковке файла изображения значка используйте PackageIcon свойство, чтобы указать путь к файлу значка относительно корневого каталога пакета. Кроме того, убедитесь, что файл включен в пакет. Размер файла изображения ограничен 1 МБ. Поддерживаемые форматы файлов включают JPEG и PNG. Рекомендуется разрешение изображений 128x128.

Например:

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

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

Пример значка пакета.

Для эквивалента nuspec ознакомьтесь со ссылкой на nuspec значок.

PackageReadmeFile

Поддерживается с NuGet предварительной версией 5.10.0 2.NET / SDK 5.0.300 и более поздних версий.

При упаковке файла readme необходимо использовать PackageReadmeFile свойство для указания пути пакета относительно корневого каталога пакета. Помимо этого, необходимо убедиться, что файл включен в пакет. Поддерживаемые форматы файлов включают только Markdown (MD).

Например:

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

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

Для эквивалента nuspec ознакомьтесь со nuspec ссылкой на readme.

Выходные сборки

nuget pack копирует выходные файлы с расширениями .exe, .dll, .xml, .winmd, .json и .pri. Выходные файлы, скопированные, зависят от того, что MSBuild предоставляется из целевого BuiltOutputProjectGroup объекта.

Существует два MSBuild свойства, которые можно использовать в файле проекта или командной строке для управления расположением выходных сборок.

  • IncludeBuildOutput: логическое значение, определяющее, следует ли включать выходные сборки в пакете.
  • BuildOutputTargetFolder: указывает папку, куда следует помещать выходные сборки. Выходные сборки (и другие выходные файлы) копируются в соответствующие папки платформы.

Ссылки на пакеты

См. раздел Ссылки на пакеты в файлах проекта.

Перекрестные ссылки между проектами

Ссылки на проект по умолчанию NuGet считаются ссылками на пакеты. Например:

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

Вы также можете добавить в ссылку на проект следующие метаданные:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Включение содержимого в пакет

Чтобы включить содержимое, добавьте дополнительные метаданные для существующего элемента <Content>. По умолчанию все данные типа "Content" включаются в пакет, если только вы не переопределите такое поведение с помощью записей, аналогичных следующим:

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

По умолчанию все данные добавляются в корень папки content и contentFiles\any\<target_framework> в пакете и сохраняют относительную структуру папок, если только не указан путь к пакету:

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

Если вы хотите скопировать все содержимое только в определенные корневые папки (вместо content них и contentFiles оба), можно использовать MSBuild свойство ContentTargetFolders, которое по умолчанию имеет значение content; contentFiles", но может быть задано любое другое имя папок. Обратите внимание, если указать "contentFiles" в ContentTargetFolders, файлы помещаются в contentFiles\any\<target_framework> или contentFiles\<language>\<target_framework> в зависимости от buildAction.

PackagePath может быть набором целевых путей, разделенных точкой с запятой. Если указан пустой путь к пакету, файл добавляется в корневой каталог пакета. Например, следующий код добавляет libuv.txt в content\myfiles, content\samples и корневой каталог пакета:

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

Существует также MSBuild свойство $(IncludeContentInPack), для которого по умолчанию используется trueзначение . Если оно имеет значение false для какого-либо проекта, то содержимое этого проекта не включается в пакет NuGet.

Другие метаданные конкретного пакета, которые можно задать для любого из перечисленных выше элементов, включают <PackageCopyToOutput> и <PackageFlatten> наборы CopyToOutput и Flatten значения для contentFiles записи в выходных данных nuspec.

Примечание.

Кроме элементов содержимого, метаданные <Pack> и <PackagePath> также можно задать для файлов с действием сборки Compile, EmbeddedResource, ApplicationDefinition, Page, Resource, SplashScreen, DesignData, DesignDataWithDesignTimeCreateableTypes, CodeAnalysisDictionary, AndroidAsset, AndroidResource, BundleResource или None.

Чтобы объект pack добавил имя файла в путь к пакету при использовании стандартных масок, путь к пакету должен заканчиваться символом разделителя папок, в противном случае этот путь считается полным путем, включающим имя файла.

IncludeSymbols

При использовании MSBuild -t:pack -p:IncludeSymbols=true соответствующие файлы .pdb копируются вместе с другими выходными файлами (.dll, .exe, .winmd, .xml, .json, .pri). Обратите внимание, что при задании IncludeSymbols=true создается обычный пакет и пакет символов.

IncludeSource

Аналогично IncludeSymbols, только копирует исходные файлы вместе с файлами .pdb. Все файлы типа Compile копируются в src\<ProjectName>\ с сохранением относительной структуры папок в итоговом пакете. То же самое происходит с исходными файлами любого ProjectReference, у которого TreatAsPackageReference имеет значение false.

Если файл типа Compile находится вне папки проекта, он просто добавляется в src\<ProjectName>\.

Упаковка выражения лицензии или файла лицензии

При использовании выражения лицензии используйте PackageLicenseExpression свойство. Пример выражения лицензии см . в примере выражения лицензии.

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

Дополнительные сведения о выражениях лицензий и лицензиях, принятых NuGetорганизацией .org, см. в разделе метаданных лицензий.

При упаковке файла лицензии используйте PackageLicenseFile свойство, чтобы указать путь к пакету относительно корневого каталога пакета. Кроме того, убедитесь, что файл включен в пакет. Например:

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

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

Пример см . в примере файла лицензии.

Примечание.

Одновременно можно указать только одно из PackageLicenseExpressionнихPackageLicenseFilePackageLicenseUrl.

Упаковка файла без расширения

В некоторых сценариях, например при упаковке файла лицензии, может потребоваться включить файл без расширения. По историческим причинам NuGet и MSBuild обрабатывать пути без расширения в качестве каталогов.

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

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

Файл без примера расширения.

IsTool

При использовании MSBuild -t:pack -p:IsTool=true все выходные файлы, как указано в сценарии Выходные сборки, копируются в папку tools вместо папки lib. Обратите внимание, что это свойство отличается от DotNetCliTool, которое указывается путем задания PackageType в файле .csproj.

Упаковка с помощью .nuspec файла

Хотя рекомендуется включить все свойства , которые обычно находятся в .nuspec файле проекта, можно использовать .nuspec файл для упаковки проекта. Для проекта, отличного от пакета SDK, который используется PackageReference, необходимо импортировать NuGet.Build.Tasks.Pack.targets , чтобы задача пакета была выполнена. Прежде чем nuspec упаковать файл, необходимо восстановить проект. (Проект в стиле SDK включает целевые объекты пакета по умолчанию.)

Целевая платформа файла проекта не имеет значения и не используется при упаковке nuspec. Следующие три MSBuild свойства относятся к упаковке с помощью .nuspec:

  1. NuspecFile: относительный или абсолютный путь к файлу .nuspec, используемому для упаковки.
  2. NuspecProperties: список разделенных точками с запятой пар "ключ-значение". Из-за работы MSBuild синтаксического анализа командной строки необходимо указать несколько свойств следующим образом: -p:NuspecProperties="key1=value1;key2=value2"
  3. NuspecBasePath: базовый путь для файла .nuspec.

Если вы используете dotnet.exe для упаковки проекта, воспользуйтесь командой, аналогичной следующей:

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

Если вы используете MSBuild для упаковки проекта, воспользуйтесь командой, аналогичной следующей:

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

Обратите внимание, что упаковка nuspec dotnet.exe или msbuild также приводит к созданию проекта по умолчанию. Это можно избежать, передав --no-build свойство в dotnet.exe, что эквивалентно настройке <NoBuild>true</NoBuild> в файле проекта, а также настройке <IncludeBuildOutput>false</IncludeBuildOutput> в файле проекта.

Пример CSPROJ-файла для упаковки 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>

Улучшенные точки расширения для создания настраиваемого пакета

Целевой pack объект предоставляет две точки расширения, которые выполняются во внутренней целевой платформе конкретной сборки. Точки расширения поддерживают, включая конкретное содержимое и сборки целевой платформы в пакет:

  • TargetsForTfmSpecificBuildOutput целевой объект: используется для файлов в папке lib или папке, указанной с помощью BuildOutputTargetFolder.
  • TargetsForTfmSpecificContentInPackage целевой объект: используется для файлов за пределами BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Напишите пользовательский целевой объект и укажите его в качестве значения $(TargetsForTfmSpecificBuildOutput) свойства. Для всех файлов, которые должны перейти в BuildOutputTargetFolder файл (lib по умолчанию), целевой объект должен записывать эти файлы в ItemGroup BuildOutputInPackage и задать следующие два значения метаданных:

  • FinalOutputPath: абсолютный путь к файлу; Если это не указано, идентификатор используется для оценки исходного пути.
  • TargetPath: (Необязательно) Задает, когда файл должен перейти в вложенную папку в lib\<TargetFramework> виде вспомогательных сборок, которые идут в соответствующие папки языка и региональных параметров. По умолчанию используется имя файла.

Пример:

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

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

TargetsForTfmSpecificContentInPackage

Напишите пользовательский целевой объект и укажите его в качестве значения $(TargetsForTfmSpecificContentInPackage) свойства. Для всех файлов, включаемых в пакет, целевой объект должен записывать эти файлы в ItemGroup TfmSpecificPackageFile и задавать следующие необязательные метаданные:

  • PackagePath: Путь к файлу, в котором файл должен быть выходным в пакете. NuGet выдает предупреждение, если в один путь пакета добавляется несколько файлов.
  • BuildAction: действие сборки, назначающее файлу, требуется только в том случае, если путь к пакету находится в папке contentFiles . Значение по умолчанию — None.

Пример.

<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

MSBuild -t:restore (который nuget restore и dotnet restore используют с проектами .NET Core) восстанавливает пакеты, на которые ссылается файл проекта:

  1. Чтение перекрестных ссылок между проектами.
  2. Чтение свойств проекта, чтобы найти промежуточную папку и целевые платформы.
  3. Передача MSBuild данных NuGetв . Build.Tasks.dll
  4. Запуск восстановления.
  5. Скачивание пакетов
  6. Запись файла ресурсов, целевых объектов и свойств.

Целевой restore объект работает для проектов с использованием формата PackageReference. MSBuild 16.5+также поддерживает packages.config формат.

Примечание.

Целевой restore объект не должен выполняться в сочетании с целевым build объектом.

Свойства восстановления

Дополнительные параметры восстановления могут быть получены из MSBuild свойств в файле проекта. Значения также можно задать из командной строки с помощью параметра -p: (см. примеры ниже).

Свойство Description
RestoreSources Разделенный точками с запятой список источников пакетов.
RestorePackagesPath Путь к папке пакетов пользователя.
RestoreDisableParallel Ограничение скачиваний до одного за раз.
RestoreConfigFile Путь к применяемому файлу Nuget.Config.
RestoreNoHttpCache Если значение true, избегайте использования кэшированных пакетов http. См. статью "Управление глобальными пакетами и папками кэша".
RestoreIgnoreFailedSources Если значение равно true, нерабочие или отсутствующие источники пакетов игнорируются.
RestoreFallbackFolders Резервные папки, используемые таким же образом, как и папка пользовательских пакетов.
RestoreAdditionalProjectSources Дополнительные источники для использования во время восстановления.
RestoreAdditionalProjectFallbackFolders Дополнительные резервные папки для использования во время восстановления.
RestoreAdditionalProjectFallbackFoldersExcludes Исключает резервные папки, указанные в RestoreAdditionalProjectFallbackFolders
RestoreTaskAssemblyFile Путь к NuGet.Build.Tasks.dll.
RestoreGraphProjectInput Разделенный точками с запятой список проектов для восстановления, который должен содержать абсолютные пути.
RestoreUseSkipNonexistentTargets При сборе проектов с помощью MSBuild нее определяется, собираются ли они с помощью SkipNonexistentTargets оптимизации. Если параметр не задан, по умолчанию используется trueзначение . Следствием является быстрое поведение, когда целевые объекты проекта не могут быть импортированы.
MSBuildProjectExtensionsPath Выходная папка, значение BaseIntermediateOutputPath по умолчанию и obj папка.
RestoreForce В проектах на основе PackageReference необходимо разрешить все зависимости, даже если последнее восстановление выполнено успешно. Указание этого флага аналогично удалению project.assets.json файла. Это не обходит http-кэш.
RestorePackagesWithLockFile Разрешение использовать файл блокировки.
RestoreLockedMode Выполните восстановление в заблокированном режиме. Это означает, что восстановление не будет повторно вычислять зависимости.
NuGetLockFilePath Настраиваемое расположение для файла блокировки. Расположение по умолчанию находится рядом с проектом и называется packages.lock.json.
RestoreForceEvaluate Принудительное восстановление для повторной компиляции зависимостей и обновления файла блокировки без каких-либо предупреждений.
RestorePackagesConfig Параметр согласия, который восстанавливает проекты с помощью packages.config. Поддержка только MSBuild -t:restore .
RestoreRepositoryPath только packages.config. Указывает каталог пакетов, в который должны быть восстановлены пакеты. SolutionDirectory будет использоваться, если он не указан.
RestoreUseStaticGraphEvaluation Переключение на использование статической оценки графа MSBuild вместо стандартной оценки. Статическое вычисление графа — это экспериментальная функция, которая значительно ускоряется для больших репозиториев и решений.

Это ExcludeRestorePackageImports внутреннее свойство, используемое NuGet. Его не следует изменять или устанавливать в каких-либо файлах MSBuild .

Примеры

Командная строка:

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

Файл проекта:

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

Выходные данные восстановления

Операция восстановления создает в папке сборки obj следующие файлы:

Файл Description
project.assets.json Содержит граф зависимостей всех ссылок на пакеты.
{projectName}.projectFileExtension.nuget.g.props Ссылки на MSBuild реквизиты, содержащиеся в пакетах
{projectName}.projectFileExtension.nuget.g.targets Ссылки на целевые MSBuild объекты, содержащиеся в пакетах

Восстановление и сборка с помощью одной MSBuild команды

Из-за того, что NuGet пакеты могут восстанавливать MSBuild целевые объекты и реквизиты, оценки восстановления и сборки выполняются с различными глобальными свойствами. Это означает, что следующее будет иметь непредсказуемое и часто неправильное поведение.

msbuild -t:restore,build

Вместо этого рекомендуется использовать следующий подход:

msbuild -t:build -restore

Та же логика применяется к другим целевым объектам, похожим buildна .

Восстановление проектов PackageReference и packages.config с помощью MSBuild

При использовании MSBuild версии 16.5+ для packages.config также поддерживаются msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Примечание.

packages.config Восстановление доступно только с MSBuild 16.5+помощью , а не с dotnet.exe

Восстановление с помощью MSBuild оценки статических графов

Примечание.

В MSBuild 16.6+ добавлена экспериментальная функция для использования статической оценки графа из командной строки, NuGet которая значительно повышает время восстановления для больших репозиториев.

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Кроме того, его можно включить, задав свойство в каталоге.Build.Props.

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

Примечание.

По состоянию на Visual Studio 2019.x и NuGet 5.x эта функция считается экспериментальной и включенной. Следуйте NuGetинструкциям /Home#9803 , чтобы узнать, когда эта функция будет включена по умолчанию.

Восстановление статических графов изменяет часть восстановления msbuild, чтение и оценку проекта, но не алгоритм восстановления! Алгоритм восстановления одинаков для всех NuGet средств (NuGet.exe, MSBuild.exe, dotnet.exe и Visual Studio).

В очень немногих сценариях восстановление статических графов может вести себя по-разному от текущего восстановления и некоторые объявленные packageReferences или ProjectReferences могут быть отсутствуют.

Чтобы упростить ваш ум, как один раз проверка, при миграции на статическое восстановление графа рекомендуется выполнить:

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

NuGetне следует сообщать о каких-либо изменениях. Если вы видите несоответствие, отправьте проблему в NuGet/Home.

Замена одной библиотеки из графа восстановления

Если операция восстановления предоставляет неправильную сборку, вы можете исключить значение по умолчанию для этого пакета, заменив его своим значением. Первый с PackageReference верхнего уровня, исключите все ресурсы:

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

После этого добавьте собственную ссылку на соответствующую локальную копию библиотеки DLL:

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