Skip to content

ROPC: dotnet publish /2 #34114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rick-Anderson merged 13 commits into from
Nov 19, 2024
Merged

ROPC: dotnet publish /2 #34114

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
53924ae
ROPC: dotnet publish /2
Rick-Anderson Nov 14, 2024
96645ab
work
Rick-Anderson Nov 14, 2024
b567b05
work
Rick-Anderson Nov 15, 2024
3be0175
work
Rick-Anderson Nov 15, 2024
4481ea4
work
Rick-Anderson Nov 15, 2024
cdf988d
work
Rick-Anderson Nov 15, 2024
fbb35c9
work
Rick-Anderson Nov 15, 2024
ef17215
work
Rick-Anderson Nov 15, 2024
b037d3b
work
Rick-Anderson Nov 15, 2024
f7775df
work
Rick-Anderson Nov 15, 2024
ff363ce
work
Rick-Anderson Nov 15, 2024
b25e224
Update aspnetcore/host-and-deploy/visual-studio-publish-profiles.md
Rick-Anderson Nov 19, 2024
d14f983
react to feedbac
Rick-Anderson Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 41 additions & 133 deletions aspnetcore/host-and-deploy/visual-studio-publish-profiles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,13 @@ uid: host-and-deploy/visual-studio-publish-profiles

By [Sayed Ibrahim Hashimi](https://github.com/sayedihashimi) and [Rick Anderson](https://twitter.com/RickAndMSFT)

This document focuses on using Visual Studio 2019 or later to create and use [publish profiles](/visualstudio/deployment/publish-overview). The publish profiles created with Visual Studio can be used with MSBuild and Visual Studio. For instructions on publishing to Azure, see <xref:tutorials/publish-to-azure-webapp-using-vs>.
This document focuses on using Visual Studio 2022 or later to create and use [publish profiles](/visualstudio/deployment/publish-overview). The publish profiles created with Visual Studio can be used with MSBuild and Visual Studio. For instructions on publishing to Azure, see <xref:tutorials/publish-to-azure-webapp-using-vs>.

For the most current and detailed information on:

* Publishing with Visual studio, see [Overview of Visual Studio Publish](/visualstudio/deployment/publish-overview)
* MSBuild, see [MSBuild](/visualstudio/msbuild/msbuild-introduction)
* Publishing with MSBuild, see [Microsoft.NET.Sdk.Publish](https://github.com/dotnet/sdk/tree/main/src/WebSdk#microsoftnetsdkpublish)

The `dotnet new mvc` command produces a project file containing the following root-level [\<Project> element](/visualstudio/msbuild/project-element-msbuild):

Expand All @@ -24,7 +30,7 @@ The `dotnet new mvc` command produces a project file containing the following ro
</Project>
```

The preceding `<Project>` element's `Sdk` attribute imports the MSBuild [properties](/visualstudio/msbuild/msbuild-properties) and [targets](/visualstudio/msbuild/msbuild-targets) from *$(MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.props* and *$(MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.targets*, respectively. The default location for `$(MSBuildSDKsPath)` (with Visual Studio 2019 Enterprise) is the *%programfiles(x86)%\Microsoft Visual Studio\2019\Enterprise\MSBuild\Sdks* folder.
The preceding `<Project>` element's `Sdk` attribute imports the MSBuild [properties](/visualstudio/msbuild/msbuild-properties) and [targets](/visualstudio/msbuild/msbuild-targets) from *$(MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.props* and *$(MSBuildSDKsPath)\Microsoft.NET.Sdk.Web\Sdk\Sdk.targets*, respectively. The default location for `$(MSBuildSDKsPath)` (with Visual Studio 2022) is the *%programfiles%\Microsoft Visual Studio\2022\Preview\MSBuild\Sdks* folder.

`Microsoft.NET.Sdk.Web` ([Web SDK](xref:razor-pages/web-sdk)) depends on other SDKs, including `Microsoft.NET.Sdk` ([.NET Core SDK](/dotnet/core/project-sdk/msbuild-props)) and `Microsoft.NET.Sdk.Razor` ([Razor SDK](xref:razor-pages/sdk)). The MSBuild properties and targets associated with each dependent SDK are imported. Publish targets import the appropriate set of targets based on the publish method used.

Expand Down Expand Up @@ -92,7 +98,7 @@ Copyright (C) Microsoft Corporation. All rights reserved.
Web1 -> C:\Webs\Web1\bin\Debug\{TARGET FRAMEWORK MONIKER}\publish\
```

The default publish folder format is *bin\Debug\\{TARGET FRAMEWORK MONIKER}\publish\\*. For example, *bin\Debug\netcoreapp2.2\publish\\*.
The default publish folder format is `bin\Debug\{TARGET FRAMEWORK MONIKER}`. For example, `bin\Release\net9.0\`

The following command specifies a `Release` build and the publishing directory:

Expand All @@ -102,7 +108,7 @@ dotnet publish -c Release -o C:\MyWebs\test

The `dotnet publish` command calls MSBuild, which invokes the `Publish` target. Any parameters passed to `dotnet publish` are passed to MSBuild. The `-c` and `-o` parameters map to MSBuild's `Configuration` and `OutputPath` properties, respectively.

MSBuild properties can be passed using either of the following formats:
[Project properties](/visualstudio/msbuild/msbuild-command-line-reference) can be passed using either of the following formats:

* `-p:<NAME>=<VALUE>`
* `/p:<NAME>=<VALUE>`
Expand All @@ -115,20 +121,21 @@ dotnet publish -c Release /p:PublishDir=//r8/release/AdminWeb

Confirm that the published app for deployment isn't running. Files in the *publish* folder are locked when the app is running. Deployment can't occur because locked files can't be copied.

See the [Microsoft.NET.Sdk.Publish](https://github.com/dotnet/sdk/tree/main/src/WebSdk#microsoftnetsdkpublish) readme file for more information.

## Publish profiles

This section uses Visual Studio 2019 or later to create a publishing profile. Once the profile is created, publishing from Visual Studio or the command line is available. Publish profiles can simplify the publishing process, and any number of profiles can exist.
This section uses Visual Studio 2022 or later to create a publishing profile. Once the profile is created, publishing from Visual Studio or the command line is available. Publish profiles can simplify the publishing process, and any number of profiles can exist.

Create a publish profile in Visual Studio by choosing one of the following paths:

* Right-click the project in **Solution Explorer** and select **Publish**.
* Select **Publish {PROJECT NAME}** from the **Build** menu.

The **Publish** tab of the app capabilities page is displayed. If the project lacks a publish profile, the **Pick a publish target** page is displayed. You're asked to select one of the following publish targets:
The **Publish** tab of the app capabilities page is displayed. Several publish targets are available, including:

* Azure App Service
* Azure App Service on Linux
* Azure Virtual Machines
* Azure
* Docker Container Registry
* Folder
* IIS, FTP, Web Deploy (for any web server)
* Import Profile
Expand All @@ -139,72 +146,32 @@ When the **Folder** publish target is selected, specify a folder path to store t

Once a publish profile is created, the **Publish** tab's content changes. The newly created profile appears in a drop-down list. Below the drop-down list, select **Create new profile** to create another new profile.

Visual Studio's publish tool produces a *Properties/PublishProfiles/{PROFILE NAME}.pubxml* MSBuild file describing the publish profile. The *.pubxml* file:
Visual Studio's publish tool produces a `Properties/PublishProfiles/{PROFILE NAME}.pubxml` MSBuild file describing the publish profile. The *.pubxml* file:

* Contains publish configuration settings and is consumed by the publishing process.
* Can be modified to customize the build and publish process.

When publishing to an Azure target, the *.pubxml* file contains your Azure subscription identifier. With that target type, adding this file to source control is discouraged. When publishing to a non-Azure target, it's safe to check in the *.pubxml* file.

Sensitive information (like the publish password) is encrypted on a per user/machine level. It's stored in the *Properties/PublishProfiles/{PROFILE NAME}.pubxml.user* file. Because this file can store sensitive information, it shouldn't be checked into source control.

For an overview of how to publish an ASP.NET Core web app, see <xref:host-and-deploy/index>. The MSBuild tasks and targets necessary to publish an ASP.NET Core web app are open-source in the [dotnet/websdk repository](https://github.com/dotnet/sdk/tree/main/src/WebSdk).

The following commands can use folder, MSDeploy, and [Kudu](https://github.com/projectkudu/kudu/wiki) publish profiles. Because MSDeploy lacks cross-platform support, the following MSDeploy options are supported only on Windows.
When publishing to an Azure target, the *.pubxml* file:

**Folder (works cross-platform):**

```dotnetcli
dotnet publish WebApplication.csproj /p:PublishProfile=<FolderProfileName>
```

```dotnetcli
dotnet build WebApplication.csproj /p:DeployOnBuild=true /p:PublishProfile=<FolderProfileName>
```
* Contains the Azure subscription identifier.
* Should not be checked into source control because the subscription identifier is sensitive information.

**MSDeploy:**
Sensitive information, for example, the publish password, is encrypted on a per user/machine level. The `Properties/PublishProfiles/{PROFILE NAME}.pubxml.user` file contains the information needed by MSBuild to retrieve the user name and password.

```dotnetcli
dotnet publish WebApplication.csproj /p:PublishProfile=<MsDeployProfileName> /p:Password=<DeploymentPassword>
```

```dotnetcli
dotnet build WebApplication.csproj /p:DeployOnBuild=true /p:PublishProfile=<MsDeployProfileName> /p:Password=<DeploymentPassword>
```

**MSDeploy package:**

```dotnetcli
dotnet publish WebApplication.csproj /p:PublishProfile=<MsDeployPackageProfileName>
```
For an overview of how to publish an ASP.NET Core web app, see <xref:host-and-deploy/index>. The MSBuild tasks and targets necessary to publish an ASP.NET Core web app are open-source in the [dotnet/websdk repository](https://github.com/dotnet/sdk/tree/main/src/WebSdk).

```dotnetcli
dotnet build WebApplication.csproj /p:DeployOnBuild=true /p:PublishProfile=<MsDeployPackageProfileName>
```
`dotnet publish` and `dotnet build`:

In the preceding examples:
* Can use folder, MSDeploy, and [Kudu](https://github.com/projectkudu/kudu/wiki) publish profiles. Because MSDeploy lacks cross-platform support, MSDeploy options are supported only on Windows.
* Support Kudu APIs to publish to Azure from any platform. Visual Studio publish supports the Kudu APIs, but it's supported by WebSDK for cross-platform publish to Azure.

* `dotnet publish` and `dotnet build` support Kudu APIs to publish to Azure from any platform. Visual Studio publish supports the Kudu APIs, but it's supported by WebSDK for cross-platform publish to Azure.
* Don't pass `DeployOnBuild` to the `dotnet publish` command.
Don't pass `DeployOnBuild` to the `dotnet publish` command.

For more information, see [Microsoft.NET.Sdk.Publish](https://github.com/dotnet/sdk/tree/main/src/WebSdk#microsoftnetsdkpublish).

Add a publish profile to the project's *Properties/PublishProfiles* folder with the following content:

```xml
<Project>
<PropertyGroup>
<PublishProtocol>Kudu</PublishProtocol>
<PublishSiteName>nodewebapp</PublishSiteName>
<UserName>username</UserName>
<Password>password</Password>
</PropertyGroup>
</Project>
```

## Folder publish example

When publishing with a profile named *FolderProfile*, use any of the following commands:
When publishing with a profile named `FolderProfile`, use any of the following commands:

```dotnetcli
dotnet publish /p:Configuration=Release /p:PublishProfile=FolderProfile
Expand All @@ -225,33 +192,11 @@ The .NET CLI's [dotnet build](/dotnet/core/tools/dotnet-build) command calls `ms

The following folder publish profile was created with Visual Studio and publishes to a network share:

```xml
<?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.
-->
<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>netcoreapp1.1</PublishFramework>
<ProjectGuid>c30c453c-312e-40c4-aec9-394a145dee0b</ProjectGuid>
<publishUrl>\\r8\Release\AdminWeb</publishUrl>
<DeleteExistingFiles>False</DeleteExistingFiles>
</PropertyGroup>
</Project>
```
[!code-xml[](visual-studio-publish-profiles/samples/FolderProfile.pubxml)]

In the preceding example:

* The `<ExcludeApp_Data>` property is present merely to satisfy an XML schema requirement. The `<ExcludeApp_Data>` property has no effect on the publish process, even if there's an *App_Data* folder in the project root. The *App_Data* folder doesn't receive special treatment as it does in ASP.NET 4.x projects.
* The `<ExcludeApp_Data>` property is present to satisfy an XML schema requirement. The `<ExcludeApp_Data>` property has no effect on the publish process, even if there's an *App_Data* folder in the project root. The *App_Data* folder doesn't receive special treatment as it does in ASP.NET 4.x projects.
* The `<LastUsedBuildConfiguration>` property is set to `Release`. When publishing from Visual Studio, the value of `<LastUsedBuildConfiguration>` is set using the value when the publish process is started. `<LastUsedBuildConfiguration>` is special and shouldn't be overridden in an imported MSBuild file. This property can, however, be overridden from the command line using one of the following approaches.
* Using the .NET CLI:

Expand All @@ -271,49 +216,18 @@ In the preceding example:

## Publish to an MSDeploy endpoint from the command line

The following example uses an ASP.NET Core web app created by Visual Studio named *AzureWebApp*. An Azure Apps publish profile is added with Visual Studio. For more information on how to create a profile, see the [Publish profiles](#publish-profiles) section.

To deploy the app using a publish profile, execute the `msbuild` command from a Visual Studio **Developer Command Prompt**. The command prompt is available in the *Visual Studio* folder of the **Start** menu on the Windows taskbar. For easier access, you can add the command prompt to the **Tools** menu in Visual Studio. For more information, see [Developer Command Prompt for Visual Studio](/dotnet/framework/tools/developer-command-prompt-for-vs#run-the-command-prompt-from-inside-visual-studio).
See [Microsoft.NET.Sdk.Publish](https://github.com/dotnet/sdk/tree/main/src/WebSdk#microsoftnetsdkpublish).

MSBuild uses the following command syntax:

```bash
msbuild {PATH}
/p:DeployOnBuild=true
/p:PublishProfile={PROFILE}
/p:Username={USERNAME}
/p:Password={PASSWORD}
```
<!-- As of Nov 2024
Copy link
Contributor

@tdykstra tdykstra Nov 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this commented out?

Copy link
Contributor Author

@Rick-Anderson Rick-Anderson Nov 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's internal for us to test fetching PW. I don't want publish how to get and save the pw, it's not hard to figure out.

On the Azure Portal, settings/configuration, enable SCM and FTB basic auth publishing.
Download the publish profile and get the username and password.

* `{PATH}`: Path to the app's project file.
* `{PROFILE}`: Name of the publish profile.
* `{USERNAME}`: MSDeploy username. The `{USERNAME}` can be found in the publish profile.
* `{PASSWORD}`: MSDeploy password. Obtain the `{PASSWORD}` from the *{PROFILE}.PublishSettings* file. Download the *.PublishSettings* file from either:
* **Solution Explorer**: Select **View** > **Cloud Explorer**. Connect with your Azure subscription. Open **App Services**. Right-click the app. Select **Download Publish Profile**.
* Azure portal: Select **Get publish profile** in the web app's **Overview** panel.
Using the default publish profile, the following command publishes to an MSDeploy endpoint:

The following example uses a publish profile named *AzureWebApp - Web Deploy*:
msbuild /p:Configuration=Release /p:DeployOnBuild=true /p:UserName="<UN> /p:Password="pw"

```bash
msbuild "AzureWebApp.csproj"
/p:DeployOnBuild=true
/p:PublishProfile="AzureWebApp - Web Deploy"
/p:Username="$AzureWebApp"
/p:Password=".........."
```

A publish profile can also be used with the .NET CLI's [dotnet msbuild](/dotnet/core/tools/dotnet-msbuild) command from a Windows command shell:

```dotnetcli
dotnet msbuild "AzureWebApp.csproj"
/p:DeployOnBuild=true
/p:PublishProfile="AzureWebApp - Web Deploy"
/p:Username="$AzureWebApp"
/p:Password=".........."
```

> [!IMPORTANT]
> The `dotnet msbuild` command is a cross-platform command and can compile ASP.NET Core apps on macOS and Linux. However, MSBuild on macOS and Linux isn't capable of deploying an app to Azure or other MSDeploy endpoints.
Delete the RG or restore the basic auth settings to disabled.
Copy link
Contributor

@tdykstra tdykstra Nov 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I presume RG is resource group, but if that isn't explained anywhere in the text, it would be worthwhile to add it.

-->

## Set the environment

Expand Down Expand Up @@ -445,7 +359,7 @@ The highlighted markup in the following example demonstrates:
* Excluding the *wwwroot\Content* folder.
* Excluding *Views\Home\About2.cshtml*.

[!code-xml[](visual-studio-publish-profiles/samples/Web1.pubxml?highlight=18-23)]
[!code-xml[](visual-studio-publish-profiles/samples/Web1.pubxml?highlight=20-25)]

The preceding example uses the `ResolvedFileToPublish` item, whose default behavior is to always copy the files provided in the `Include` attribute to the published site. Override the default behavior by including a `<CopyToPublishDirectory>` child element with inner text of either `Never` or `PreserveNewest`. For example:

Expand All @@ -462,14 +376,7 @@ For more deployment samples, see the [Web SDK README file](https://github.com/do

The built-in `BeforePublish` and `AfterPublish` targets execute a target before or after the publish target. Add the following elements to the publish profile to log console messages both before and after publishing:

```xml
<Target Name="CustomActionsBeforePublish" BeforeTargets="BeforePublish">
<Message Text="Inside BeforePublish" Importance="high" />
</Target>
<Target Name="CustomActionsAfterPublish" AfterTargets="AfterPublish">
<Message Text="Inside AfterPublish" Importance="high" />
</Target>
```
[!code-xml[](visual-studio-publish-profiles/samples/TP_before.pubxml?highlight=30-35)]

## Publish to a server using an untrusted certificate

Expand All @@ -494,6 +401,7 @@ Select the [Debug Console](https://github.com/projectkudu/kudu/wiki/Kudu-console

## Additional resources

* [Web Deploy](https://www.iis.net/downloads/microsoft/web-deploy) (MSDeploy) simplifies deployment of web apps and websites to IIS servers.
* [Web SDK README file](https://github.com/dotnet/sdk/tree/main/src/WebSdk)
* [Web SDK GitHub repository](https://github.com/dotnet/websdk/issues): File issues and request features for deployment.
* [Web Deploy](https://www.iis.net/downloads/microsoft/web-deploy) (MSDeploy) simplifies deployment of web apps and websites to IIS servers.
* <xref:host-and-deploy/iis/transform-webconfig>
17 changes: 17 additions & 0 deletions aspnetcore/host-and-deploy/visual-studio-publish-profiles/samples/FolderProfile.pubxml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<?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>
Loading
Loading