Профили публикации Visual Studio (.pubxml) для развертывания приложений ASP.NET Core

Авторы: Саид Ибрагим Хашими (Sayed Ibrahim Hashimi) и Рик Андерсон

В этом документе основное внимание уделяется использованию Visual Studio 2022 или более поздней версии для создания и использования профилей публикации. Профили публикации, созданные с помощью Visual Studio, можно применять в MSBuild и Visual Studio. Инструкции по публикации в Azure см. в статье Публикация приложения ASP.NET Core в Azure с помощью Visual Studio.

Для получения наиболее актуальных и подробных сведений об этом:

• Публикация с помощью Visual Studio см. в статье "Обзор публикации Visual Studio"
• MSBuild, см. раздел MSBuild
• Публикация с помощью MSBuild см. в статье Microsoft.NET.Sdk.Publish

Команда dotnet new mvc создает файл проекта со следующим элементом <Project> element на корневом уровне:

<Project Sdk="Microsoft.NET.Sdk.Web">
    <!-- omitted for brevity -->
</Project>

В описанном выше элементе <Project> атрибут Sdk импортирует свойства и целевые объекты для MSBuild из файлов $(MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\ SDK.props и $(MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.targets, соответственно. Расположение по умолчанию для $(MSBuildSDKsPath) (с Visual Studio 2022) — это папка %programfiles%\Microsoft Visual Studio\2022\Preview\MSBuild\Sdks .

Microsoft.NET.Sdk.Web (Веб-пакет SDK) зависит от других пакетов SDK, включая Microsoft.NET.Sdk (пакет SDK для .NET) и Microsoft.NET.Sdk.Razor (Razor пакет SDK). Импортируются свойства и целевые объекты MSBuild, связанные с каждым из зависимых пакетов SDK. Целевые объекты публикации импортируют подходящий набор целевых объектов в зависимости от используемых методов публикации.

Когда MSBuild или Visual Studio загружает проект, выполняются следующие обобщенные действия:

• Build project
• вычисление файлов для публикации;
• публикация файлов в месте назначения;

вычисление элементов проекта.

После загрузки проекта вычисляются элементы (файлы) проекта MSBuild. Порядок обработки файла определяется типом элемента. По умолчанию файлы с расширением .cs включаются в список элементов Compile. Файлы в списке элементов Compile компилируются.

Список элементов Content содержит файлы, предназначенные для публикации, а также результаты сборки. По умолчанию в список элементов wwwroot\** включаются файлы, соответствующие шаблонам **\*.config, **\*.json и Content. Например, wwwroot\** соответствует всем файлам в папке wwwroot и всех ее вложенных папках.

Чтобы явно добавить файл в список публикации, добавьте файл непосредственно в файл, как показано в .csprojразделе "Включить файлы ".

При нажатии кнопки Публикация в Visual Studio или при публикации из командной строки происходит следующее:

• Вычисляются свойства и (или) элементы (файлы, требующие сборки).
• (Только в Visual Studio). Восстанавливаются пакеты NuGet. (Восстановление выполняется пользователем в интерфейсе командной строки.)
• Выполняется сборка проекта.
• Вычисляются публикуемые элементы (файлы, требующие публикации).
• Публикуется проект (вычисляемые файлы копируются в место назначения публикации.)

Когда проект ASP.NET Core ссылается на Microsoft.NET.Sdk.Web в файле проекта, файл app_offline.htm помещается в корневой каталог веб-приложения. Когда файл присутствует, модуль ядра ASP.NET корректно завершает работу приложения и обслуживает app_offline.htm файл во время развертывания. Дополнительные сведения см. в разделе Справочник по конфигурации модуля ASP.NET Core.

Простая публикация из командной строки

Публикация командной строки работает на всех. Поддерживаемые NET платформы и не требуют Visual Studio. В следующих примерах команда публикации dotnet CLI .NET выполняется из каталога проекта (который содержит .csproj файл). Если папка проекта не является текущим рабочим каталогом, явным образом передайте путь к файлу проекта. For example:

dotnet publish C:\Webs\Web1

Для создания и публикации веб-приложения выполните следующие команды.

dotnet new mvc
dotnet publish

Команда dotnet publish создает подобные выходные данные:

C:\Webs\Web1>dotnet publish
Restore complete (0.4s)
  Web1 succeeded (9.2s) → bin\Release\net9.0\publish\

Формат папки публикации по умолчанию .bin\Debug\{TARGET FRAMEWORK MONIKER} Например: bin\Release\net9.0\

Следующая команда определяет сборку Release и папку для публикации.

dotnet publish -c Release -o C:\MyWebs\test

Команда dotnet publish вызывает метод MSBuild, который, в свою очередь, вызывает целевой объект Publish. Все параметры, передаваемые в dotnet publish, передаются далее в MSBuild. Параметры -c и -o сопоставляются со свойствами MSBuild Configuration и OutputPath соответственно.

Свойства MSBuild можно передать с помощью любого из следующих форматов:

• -p:<NAME>=<VALUE>
• /p:<NAME>=<VALUE>

Например, следующая команда публикует сборку Release в общую сетевую папку. Сетевая папка указана с косой чертой (r8/) и работает на всех поддерживаемых платформах .NET.

dotnet publish -c Release /p:PublishDir=//r8/release/AdminWeb

Убедитесь, что приложение, публикуемое для развертывания, не запущено. Во время выполнения приложения файлы в папке publish блокируются. Заблокированные файлы нельзя скопировать, так что развертывание в этом случае не произойдет.

Дополнительные сведения см. в файле чтения Microsoft.NET.Sdk.Publish .

Publish profiles

В этом разделе для создания профиля публикации используется Visual Studio 2022 или более поздней версии. После создания профиля публикацию можно выполнять из Visual Studio или из командной строки. Профили публикации упрощают процесс публикации. Вы можете создать любое количество профилей.

Создайте профиль публикации в Visual Studio, выбрав один из следующих методов:

• Щелкните правой кнопкой мыши проект в обозревателе решений и выберите Опубликовать.
• Выберите команду Опубликовать {имя проекта} в меню Сборка.

Откроется вкладка Публикация на странице возможностей приложения. Доступны несколько целевых объектов публикации, в том числе:

• Azure
• Реестр контейнеров Docker
• Folder
• IIS, FTP, веб-развертывание (для любого веб-сервера)
• Import Profile

Чтобы определить наиболее подходящий целевой объект публикации, см. раздел Какие варианты публикации мне подойдут.

Если вы выбрали Папка в качестве целевого объекта, укажите путь к папке, в которой будут храниться опубликованные ресурсы. Путь к папке по умолчанию: bin{КОНФИГУРАЦИЯ ПРОЕКТА}\{МОНИКЕР ЦЕЛЕВОЙ ПЛАТФОРМЫ}\publish. Например, bin\Release\netcoreapp2.2\publish. Нажмите кнопку Создать профиль, чтобы завершить процесс.

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

Средство публикации Visual Studio создает Properties/PublishProfiles/{PROFILE NAME}.pubxml MSBuild-файл, описывающий профиль публикации. PUBXML-файл:

• Содержит настройки конфигурации публикации и используется в процессе публикации.
• Может меняться для настройки процесса сборки и публикации.

При публикации в целевом объекте Azure pubxml-файл :

• Содержит идентификатор подписки Azure.
• Не следует проверять управление версиями, так как идентификатор подписки является конфиденциальной информацией.

Конфиденциальная информация, например, пароль публикации, шифруется на уровне пользователя или компьютера. Файл Properties/PublishProfiles/{PROFILE NAME}.pubxml.user содержит сведения, необходимые MSBuild для получения имени пользователя и пароля.

Общие сведения о публикации веб-приложений в ASP.NET Core см. в статье Размещение и развертывание ASP.NET Core. Открытый исходный код задач MSBuild и целевых объектов, необходимых для публикации веб-приложения ASP.NET Core, размещен в репозитории dotnet/websdk.

dotnet publish и dotnet build:

• Можно использовать профили публикации папок, MSDeploy и Kudu . Поскольку MSDeploy не поддерживает кроссплатформенную поддержку, параметры MSDeploy поддерживаются только в Windows.
• Поддержка API Kudu для публикации в Azure с любой платформы. Публикация с помощью Visual Studio поддерживает API Kudu, но для кроссплатформенной публикации в Azure их поддерживает WebSDK.

Не передавайте DeployOnBuild команде dotnet publish.

Дополнительные сведения см. в документации по Microsoft.NET.Sdk.Publish.

Пример публикации папки

При публикации с именем FolderProfileпрофиля используйте любую из следующих команд:

dotnet publish /p:Configuration=Release /p:PublishProfile=FolderProfile

dotnet build /p:DeployOnBuild=true /p:PublishProfile=FolderProfile

msbuild /p:DeployOnBuild=true /p:PublishProfile=FolderProfile

Команда dotnet build .NET CLI msbuild для запуска процесса сборки и публикации. Команды dotnet build и msbuild эквивалентны, если они передаются в профиле папки. При прямом вызове msbuild на платформе Windows используется версия MSBuild для .NET Framework. Вызов dotnet build не в профиле папки:

• Вызывает msbuild, который использует MSDeploy.
• Приводит к сбою (даже при работе в Windows). Для публикации профилей, отличных от профиля папки, вызывайте msbuild напрямую.

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

<?xml version="1.0" encoding="utf-8"?>
<!--
https://go.microsoft.com/fwlink/?LinkID=208121.
-->
<Project>
  <PropertyGroup>
    <DeleteExistingFiles>false</DeleteExistingFiles>
    <ExcludeApp_Data>false</ExcludeApp_Data>
    <LaunchSiteAfterPublish>true</LaunchSiteAfterPublish>
    <LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
    <LastUsedPlatform>Any CPU</LastUsedPlatform>
    <PublishProvider>FileSystem</PublishProvider>
    <PublishUrl>\\r8\Release\AdminWeb</PublishUrl>
    <WebPublishMethod>FileSystem</WebPublishMethod>
    <_TargetId>Folder</_TargetId>
  </PropertyGroup>
</Project>

В предыдущем примере:

• Свойство <ExcludeApp_Data> представлено для удовлетворения требования схемы XML. Свойство <ExcludeApp_Data> не влияет на процесс публикации даже при наличии папки App_Data в корневом каталоге проекта. Папка App_Data не получает специальной обработки, как в проектах ASP.NET 4.x.
• Свойство <LastUsedBuildConfiguration> имеет значение Release. При публикации из Visual Studio значение <LastUsedBuildConfiguration> указывается на основе значения, которое использовалось при запуске процесса публикации. <LastUsedBuildConfiguration> имеет особое значение и его не следует переопределять в импортируемом файле MSBuild. Тем не менее, это свойство можно переопределить в командной строке с помощью одного из следующих подходов.

  • С использованием .NET CLI:

    dotnet publish /p:Configuration=Release /p:PublishProfile=FolderProfile
    

    dotnet build -c Release /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
    

  • Using MSBuild:

    msbuild /p:Configuration=Release /p:DeployOnBuild=true /p:PublishProfile=FolderProfile
    

Публикация конечной точки MSDeploy из командной строки

See Microsoft.NET.Sdk.Publish.

Указание среды

Включите свойство <EnvironmentName> в профиле публикации (PUBXML) или файле проекта, чтобы задать среду приложения:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Если вам нужно преобразовать web.config (например, задать переменные среды на основе конфигурации, профиля или среды), см. статью Преобразование web.config.

Exclude files

При публикации веб-приложений ASP.NET Core включаются следующие ресурсы:

• Build artifacts
• Папки и файлы, соответствующие следующим шаблонам глоббинга:
  • **\*.config (например, web.config);
  • **\*.json (например, appsettings.json)
  • wwwroot\**

MSBuild поддерживает стандартные маски. Например, представленный ниже элемент <Content> запретит копирование текстовых файлов (.txt) из папки wwwroot\content и всех ее подпапок.

<ItemGroup>
  <Content Update="wwwroot/content/**/*.txt" CopyToPublishDirectory="Never" />
</ItemGroup>

Предыдущая разметка может быть добавлена в профиль публикации или .csproj файл. При добавлении .csproj в файл правило добавляется ко всем профилям публикации в проекте.

Следующий элемент <MsDeploySkipRules> исключает все файлы из папки wwwroot\content.

<ItemGroup>
  <MsDeploySkipRules Include="CustomSkipFolder">
    <ObjectName>dirPath</ObjectName>
    <AbsolutePath>wwwroot\\content</AbsolutePath>
  </MsDeploySkipRules>
</ItemGroup>

Элемент <MsDeploySkipRules> не удаляет пропускаемые целевые объекты с сайта развертывания. Целевые файлы и папки, указанные в элементе <Content>, будут удалены с сайта развертывания. Допустим, что в развернутом веб-приложении есть следующие файлы.

• Views/Home/About1.cshtml
• Views/Home/About2.cshtml
• Views/Home/About3.cshtml

Если вы добавите указанные ниже элементы <MsDeploySkipRules>, эти файлы не будут удалены с сайта развертывания.

<ItemGroup>
  <MsDeploySkipRules Include="CustomSkipFile">
    <ObjectName>filePath</ObjectName>
    <AbsolutePath>Views\\Home\\About1.cshtml</AbsolutePath>
  </MsDeploySkipRules>

  <MsDeploySkipRules Include="CustomSkipFile">
    <ObjectName>filePath</ObjectName>
    <AbsolutePath>Views\\Home\\About2.cshtml</AbsolutePath>
  </MsDeploySkipRules>

  <MsDeploySkipRules Include="CustomSkipFile">
    <ObjectName>filePath</ObjectName>
    <AbsolutePath>Views\\Home\\About3.cshtml</AbsolutePath>
  </MsDeploySkipRules>
</ItemGroup>

Приведенные выше элементы <MsDeploySkipRules> запрещают развертывание пропускаемых файлов. Эти файлы не будут удалены, если они уже развернуты.

Следующий элемент <Content> удаляет целевые файлы на сайте развертывания.

<ItemGroup>
  <Content Update="Views/Home/About?.cshtml" CopyToPublishDirectory="Never" />
</ItemGroup>

Применение указанного выше элемента <Content> при развертывании из командной строки дает следующий результат:

MSDeployPublish:
  Starting Web deployment task from source: manifest(C:\Webs\Web1\obj\Release\{TARGET FRAMEWORK MONIKER}\PubTmp\Web1.SourceManifest.
  xml) to Destination: auto().
  Deleting file (Web11112\Views\Home\About1.cshtml).
  Deleting file (Web11112\Views\Home\About2.cshtml).
  Deleting file (Web11112\Views\Home\About3.cshtml).
  Updating file (Web11112\web.config).
  Updating file (Web11112\Web1.deps.json).
  Updating file (Web11112\Web1.dll).
  Updating file (Web11112\Web1.pdb).
  Updating file (Web11112\Web1.runtimeconfig.json).
  Successfully executed Web deployment task.
  Publish Succeeded.
Done Building Project "C:\Webs\Web1\Web1.csproj" (default targets).

Include files

В следующих разделах описываются различные подходы для включения файла во время публикации. В разделе Включение общего файла используется элемент DotNetPublishFiles, предоставляемый файлом целевых объектов публикации в веб-пакете SDK. В разделе "Выборочное включение файлов " используется ResolvedFileToPublish элемент, который предоставляется файлом целевых объектов публикации в пакете SDK для .NET. Так как веб-пакет SDK зависит от пакета SDK для .NET, любой элемент можно использовать в проекте ASP.NET Core.

Включение общих файлов

Элемент <ItemGroup> в приведенном ниже примере демонстрирует копирование папки, расположенной за пределами папки проекта, в папку опубликованного сайта. Файлы, добавленные в следующий элемент разметки <ItemGroup>, включены по умолчанию.

<ItemGroup>
  <_CustomFiles Include="$(MSBuildProjectDirectory)/../images/**/*" />
  <DotNetPublishFiles Include="@(_CustomFiles)">
    <DestinationRelativePath>wwwroot/images/%(RecursiveDir)%(Filename)%(Extension)</DestinationRelativePath>
  </DotNetPublishFiles>
</ItemGroup>

Предыдущая разметка:

• Можно добавить в .csproj файл или профиль публикации. Если он добавлен .csproj в файл, он включен в каждый профиль публикации в проекте.
• Объявляет элемент _CustomFiles для хранения файлов, соответствующих стандартной маске атрибута Include. Папка образов, указанная в шаблоне, находится вне каталога проекта. Зарезервированное свойство с именем $(MSBuildProjectDirectory) разрешается в абсолютный путь файла проекта.
• Предоставляет список файлов элементу DotNetPublishFiles. По умолчанию элемент <DestinationRelativePath> в элементе пуст. Значение по умолчанию переопределяется в разметке и использует стандартные метаданные элементов, например %(RecursiveDir). Внутренний текст представляет папку wwwroot/images опубликованного сайта.

Включение выборочных файлов

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

• Копирование файла, расположенного вне проекта, в папку wwwroot опубликованного сайта. Имя файла ReadMe2.md сохраняется.
• Исключение папки wwwroot\Content.
• Исключение Views\Home\About2.cshtml.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" 
         xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <WebPublishMethod>FileSystem</WebPublishMethod>
    <PublishProvider>FileSystem</PublishProvider>
    <LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
    <LastUsedPlatform>Any CPU</LastUsedPlatform>
    <SiteUrlToLaunchAfterPublish />
    <LaunchSiteAfterPublish>True</LaunchSiteAfterPublish>
    <ExcludeApp_Data>False</ExcludeApp_Data>
    <PublishFramework />
    <ProjectGuid>
      <GUID Here=""></GUID>
    </ProjectGuid>
    <publishUrl>bin\Release\PublishOutput</publishUrl>
    <DeleteExistingFiles>False</DeleteExistingFiles>
  </PropertyGroup>
  <ItemGroup>
    <ResolvedFileToPublish Include="..\ReadMe2.md">
      <RelativePath>wwwroot\ReadMe2.md</RelativePath>
    </ResolvedFileToPublish>

    <Content Update="wwwroot\Content\**\*" CopyToPublishDirectory="Never" />
    <Content Update="Views\Home\About2.cshtml" CopyToPublishDirectory="Never" />
  </ItemGroup>
</Project>

В предыдущем примере используется элемент ResolvedFileToPublish, поведение по умолчанию которого — всегда копировать файлы, предоставленные в атрибуте Include опубликованному сайту. Переопределите поведение по умолчанию, включив дочерний элемент <CopyToPublishDirectory> с внутренним текстом Never или PreserveNewest. For example:

<ResolvedFileToPublish Include="..\ReadMe2.md">
  <RelativePath>wwwroot\ReadMe2.md</RelativePath>
  <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
</ResolvedFileToPublish>

Дополнительные примеры развертывания см. в файле README из репозитория веб-пакета SDK.

Выполнение целевого объекта до или после публикации

Встроенные целевые объекты BeforePublish и AfterPublish позволяют выполнить целевой объект до или после его публикации. Добавьте следующие элементы в профиль публикации, чтобы сохранять сообщения в консоли, возвращаемые до и после публикации:

<?xml version="1.0" encoding="utf-8"?>
<!--
This file is used by the publish/package process of your Web project. You can customize the behavior of this process
by editing this MSBuild file. In order to learn more about this please visit https://go.microsoft.com/fwlink/?LinkID=208121. 
-->
<Project>
  <PropertyGroup>
    <WebPublishMethod>MSDeploy</WebPublishMethod>
    <ResourceId>/subscriptions/SomeGuid/resourcegroups/TP_RG/providers/Microsoft.Web/sites/TP22</ResourceId>
    <ResourceGroup>TP_RG</ResourceGroup>
    <PublishProvider>AzureWebSite</PublishProvider>
    <LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
    <LastUsedPlatform>Any CPU</LastUsedPlatform>
    <SiteUrlToLaunchAfterPublish>https://tp22.azurewebsites.net</SiteUrlToLaunchAfterPublish>
    <LaunchSiteAfterPublish>true</LaunchSiteAfterPublish>
    <ExcludeApp_Data>false</ExcludeApp_Data>
    <ProjectGuid>GuidHere</ProjectGuid>
    <MSDeployServiceURL>something.scm.azurewebsites.net:443</MSDeployServiceURL>
    <DeployIisAppPath>myDeploysIISpath</DeployIisAppPath>
    <RemoteSitePhysicalPath />
    <SkipExtraFilesOnServer>true</SkipExtraFilesOnServer>
    <MSDeployPublishMethod>WMSVC</MSDeployPublishMethod>
    <EnableMSDeployBackup>true</EnableMSDeployBackup>
    <EnableMsDeployAppOffline>true</EnableMsDeployAppOffline>
    <UserName />
    <_SavePWD>false</_SavePWD>
    <_DestinationType>AzureWebSite</_DestinationType>
    <InstallAspNetCoreSiteExtension>false</InstallAspNetCoreSiteExtension>
  </PropertyGroup>
    <Target Name="CustomActionsBeforePublish" BeforeTargets="BeforePublish">
        <Message Text="Inside BeforePublish" Importance="high" />
    </Target>
    <Target Name="CustomActionsAfterPublish" AfterTargets="AfterPublish">
        <Message Text="Inside AfterPublish" Importance="high" />
    </Target>
</Project>

Публикация на сервере с использованием сертификата без доверия

Добавьте свойство <AllowUntrustedCertificate> со значением True в профиль публикации:

<PropertyGroup>
  <AllowUntrustedCertificate>True</AllowUntrustedCertificate>
</PropertyGroup>

Служба Kudu

Чтобы просмотреть файлы в развертывании веб-приложения службы приложений Azure, используйте службу Kudu. Добавьте к имени веб-приложения маркер scm. For example:

Для просмотра, редактирования, удаления и (или) добавления файлов выберите в меню пункт Консоль отладки.

Additional resources

• ФАЙЛ README веб-пакета SDK
• Репозиторий GitHub веб-пакета SDK: проблемы с файлами и функции запроса для развертывания.
• Веб-развертывание (MSDeploy) упрощает развертывание веб-приложений и веб-сайтов на серверах IIS.
• Transform web.config