shortening lines in publish doc before changes
Sayed Ibrahim Hashimi
parent
5a1a06b2c4
commit
4d440efce7
|
|
@ -16,11 +16,19 @@ uid: publishing/web-publishing-vs
|
|||
|
||||
By [Sayed Ibrahim Hashimi](https://github.com/sayedihashimi)
|
||||
|
||||
The web publish experience for ASP.NET Core projects has significantly changed from ASP.NET 4. This doc will provide an overview of the changes and instructions on how to customize the publish process. Unless stated otherwise, the instructions in this article are for publishing from Visual Studio. For an overview of how to publish a web app on ASP.NET Core see [Publishing and Deployment](index.md).
|
||||
The web publish experience for ASP.NET Core projects has significantly changed from ASP.NET 4. This doc will provide an overview of the changes and
|
||||
instructions on how to customize the publish process. Unless stated otherwise, the instructions in this article are for publishing from Visual Studio.
|
||||
For an overview of how to publish a web app on ASP.NET Core see [Publishing and Deployment](index.md).
|
||||
|
||||
In ASP.NET when you publish a Visual Studio web project MSBuild is used to drive the entire process. The project file (.csproj or .vbproj) is used to gather the files that need to be published as well as perform any updates during publish (for example updating web.config). The project file contains the full list of files as well as their type. That information is used to determine the files to publish. The logic was implemented in an MSBuild .targets file. During the publish process MSBuild will call Web Deploy (msdeploy.exe) to transfer the files to the final location. To customize the publish process you would need to update the publish profile, or project file, with custom MSBuild elements.
|
||||
In ASP.NET when you publish a Visual Studio web project MSBuild is used to drive the entire process. The project file (.csproj or .vbproj) is used to gather
|
||||
the files that need to be published as well as perform any updates during publish (for example updating web.config). The project file contains the full list
|
||||
of files as well as their type. That information is used to determine the files to publish. The logic was implemented in an MSBuild .targets file. During the
|
||||
publish process MSBuild will call Web Deploy (msdeploy.exe) to transfer the files to the final location. To customize the publish process you would need to
|
||||
update the publish profile, or project file, with custom MSBuild elements.
|
||||
|
||||
In ASP.NET Core the publish process has been simplified, we no longer store a reference to files that the project contains. All files are included in the project by default (files can be excluded from the project or from publish by updating *project.json*). When you publish an ASP.NET Core project from Visual Studio the following happens:
|
||||
In ASP.NET Core the publish process has been simplified, we no longer store a reference to files that the project contains. All files are included in the
|
||||
project by default (files can be excluded from the project or from publish by updating *project.json*). When you publish an ASP.NET Core project from
|
||||
Visual Studio the following happens:
|
||||
|
||||
1. A publish profile is created at `Properties\PublishProfiles\profilename.pubxml`. The publish profile is an MSBuild file.
|
||||
|
||||
|
|
@ -38,11 +46,15 @@ The following image shows a visualization of this process.
|
|||
|
||||
In the image above each black circle ● indicates an extension point, we will cover each extension point later in this document.
|
||||
|
||||
When you start a publish operation, the publish dialog is closed and then MSBuild is called to start the process. Visual Studio calls MSBuild to do this so that you can have parity with publishing when using Visual Studio or the command line. The MSBuild layer is pretty thin, for the most part it just calls `dotnet publish`. Let’s take a closer look at `dotnet publish`.
|
||||
When you start a publish operation, the publish dialog is closed and then MSBuild is called to start the process. Visual Studio calls MSBuild to do this so that
|
||||
you can have parity with publishing when using Visual Studio or the command line. The MSBuild layer is pretty thin, for the most part it just calls `dotnet publish`.
|
||||
Let’s take a closer look at `dotnet publish`.
|
||||
|
||||
The `dotnet publish` command will inspect project.json and the project folder to determine the files which need to be published. It will place the files needed to run the application in a single folder ready to be transferred to the final destination.
|
||||
The `dotnet publish` command will inspect project.json and the project folder to determine the files which need to be published. It will place the files needed to
|
||||
run the application in a single folder ready to be transferred to the final destination.
|
||||
|
||||
After `dotnet publish` has completed, the PowerShell script for the publish profile is called. Now that we have briefly discussed how publishing works at a high level let’s take a look at the structure of the PowerShell script created for publishing.
|
||||
After `dotnet publish` has completed, the PowerShell script for the publish profile is called. Now that we have briefly discussed how publishing works at a high
|
||||
level let’s take a look at the structure of the PowerShell script created for publishing.
|
||||
|
||||
When you create a publish profile in Visual Studio for an ASP.NET Core project a PowerShell script is created that has the following structure.
|
||||
|
||||
|
|
@ -70,17 +82,25 @@ When you create a publish profile in Visual Studio for an ASP.NET Core project a
|
|||
}
|
||||
```
|
||||
|
||||
In the above snippet some functions have been removed for readability. Those functions are used to bootstrap the script in the case that it’s executed from a machine which doesn’t have Visual Studio installed. The script contains the following important elements:
|
||||
In the above snippet some functions have been removed for readability. Those functions are used to bootstrap the script in the case that it’s executed
|
||||
from a machine which doesn’t have Visual Studio installed. The script contains the following important elements:
|
||||
|
||||
1. Script parameters
|
||||
2. Publish module version
|
||||
3. Call to Publish-AspNet
|
||||
|
||||
The parameters of the script define the contract between Visual Studio and the PowerShell script. You should not change the declared parameters because Visual Studio depends on those. You can add additional parameters, but they must be added at the end.
|
||||
The parameters of the script define the contract between Visual Studio and the PowerShell script. You should not change the declared parameters because Visual Studio
|
||||
depends on those. You can add additional parameters, but they must be added at the end.
|
||||
|
||||
The publish module version, denoted by `$publishModuleVersion`, defines the version of the web publish module that will be used. Valid version numbers can be found from published versions of the [publish-module NuGet package](https://www.nuget.org/packages/publish-module) on nuget.org. Once you create a publish profile the script definition is locked to a particular version of the publish-module package. If you need to update the version of the script you can delete the .ps1 file and then publish again in Visual Studio to get a new script created.
|
||||
The publish module version, denoted by `$publishModuleVersion`, defines the version of the web publish module that will be used. Valid version numbers can be found
|
||||
from published versions of the [publish-module NuGet package](https://www.nuget.org/packages/publish-module) on nuget.org. Once you create a publish profile the
|
||||
script definition is locked to a particular version of the publish-module package. If you need to update the version of the script you can delete the .ps1 file
|
||||
and then publish again in Visual Studio to get a new script created.
|
||||
|
||||
The call to Publish-AspNet moves the files from your local machine to the final destination. Publish-AspNet will be passed all the properties defined in the .pubxml file, even custom properties. For Web Deploy publish, msdeploy.exe will be called to publish the files to the destination. Publish-AspNet is passed the same parameters as the original script. You can get more info on the parameters for Publish-AspNet use Get-Help Publish-AspNet. If you get an error that the publish-module is not loaded, you can load it with
|
||||
The call to Publish-AspNet moves the files from your local machine to the final destination. Publish-AspNet will be passed all the properties defined in the .pubxml
|
||||
file, even custom properties. For Web Deploy publish, msdeploy.exe will be called to publish the files to the destination. Publish-AspNet is passed the same
|
||||
parameters as the original script. You can get more info on the parameters for Publish-AspNet use Get-Help Publish-AspNet. If you get an error that the publish-module
|
||||
is not loaded, you can load it with
|
||||
|
||||
```none
|
||||
Import-Module “${env:ProgramFiles(x86)}\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\Web Tools\Publish\Scripts\1.0.1\publish-module.psm1"
|
||||
|
|
@ -96,13 +116,20 @@ The image above shows the three main extension points, you’re most likely to u
|
|||
|
||||
1. Customize the call to `dotnet publish`
|
||||
|
||||
Most developers will not need to customize this extension point. Visual Studio starts the publish process by calling an MSBuild target. This target will take care of initializing the environment and calling `dotnet publish` to layout the files. If you need to customize that call in a way that is not enabled by the publish dialog then you can use MSBuild elements in either the project file (.xproj file) or the publish profile (.pubxml file). We won’t get into details of how to do that here as it’s an advanced scenario that few will need to extend.
|
||||
Most developers will not need to customize this extension point. Visual Studio starts the publish process by calling an MSBuild target. This target will take care of
|
||||
initializing the environment and calling `dotnet publish` to layout the files. If you need to customize that call in a way that is not enabled by the publish dialog
|
||||
then you can use MSBuild elements in either the project file (.xproj file) or the publish profile (.pubxml file). We won’t get into details of how to do that here as
|
||||
it’s an advanced scenario that few will need to extend.
|
||||
|
||||
2. Customize `dotnet publish`
|
||||
|
||||
As stated previously `dotnet publish` is a command-line utility that can be used to help publish your ASP.NET Core application. This is a cross platform command-line utility (that is, you can use it on Windows, Mac or Linux) and does not require Visual Studio. If you are working on a team in which some developers are not using Visual Studio, then you may want to script building and publishing. When `dotnet publish` is executed it can be configured to execute custom commands before or after execution. The commands will be listed in project.json in the scripts section.
|
||||
As stated previously `dotnet publish` is a command-line utility that can be used to help publish your ASP.NET Core application. This is a cross platform command-line
|
||||
utility (that is, you can use it on Windows, Mac or Linux) and does not require Visual Studio. If you are working on a team in which some developers are not using
|
||||
Visual Studio, then you may want to script building and publishing. When `dotnet publish` is executed it can be configured to execute custom commands before or after
|
||||
execution. The commands will be listed in project.json in the scripts section.
|
||||
|
||||
The supported scripts for publish are prepublish and postpublish. The ASP.NET Core Web Application template uses the prepublish step by default. The relevant snippet from *project.json* is shown below.
|
||||
The supported scripts for publish are prepublish and postpublish. The ASP.NET Core Web Application template uses the prepublish step by default. The relevant snippet
|
||||
from *project.json* is shown below.
|
||||
|
||||
```javascript
|
||||
"scripts": {
|
||||
|
|
@ -112,7 +139,9 @@ The image above shows the three main extension points, you’re most likely to u
|
|||
|
||||
Here multiple comma separated calls are declared.
|
||||
|
||||
When Visual Studio is used the prepublish and postpublish steps are executed as a part of the call to `dotnet publish`. The postpublish script from *project.json* is executed before the files are published to the remote destination because that takes place immediately after `dotnet publish` completes. In the next step we cover customizing the PowerShell script to control what happens to the files after they reach the target destination.
|
||||
When Visual Studio is used the prepublish and postpublish steps are executed as a part of the call to `dotnet publish`. The postpublish script from *project.json* is
|
||||
executed before the files are published to the remote destination because that takes place immediately after `dotnet publish` completes. In the next step we cover
|
||||
customizing the PowerShell script to control what happens to the files after they reach the target destination.
|
||||
|
||||
3. Customize the publish profile PowerShell Script
|
||||
|
||||
|
|
@ -120,7 +149,8 @@ After creating a publish profile in Visual Studio the PowerShell script `Propert
|
|||
|
||||
1. Runs `dotnet publish`, which will package the web project into a temporary folder to prepare it for the next phase of publishing.
|
||||
|
||||
2. The profile PowerShell script is directly invoked. The publish properties and the path to the temporary folder are passed in as parameters. Note, the temporary folder will be deleted on each publish.
|
||||
2. The profile PowerShell script is directly invoked. The publish properties and the path to the temporary folder are passed in as parameters. Note, the temporary folder
|
||||
will be deleted on each publish.
|
||||
|
||||
As mentioned previously the most important line in the default publish script is the call to `Publish-AspNet`. The call to Publish-AspNet:
|
||||
|
||||
|
|
@ -128,9 +158,13 @@ As mentioned previously the most important line in the default publish script is
|
|||
|
||||
* The publish properties are passed in the script parameter `$publishProperties`.
|
||||
|
||||
* `$publishProperties` is a PowerShell hashtable which contains all the properties declared in the profile .pubxml file. It also includes values for file text replacements or files to exclude. For more info on the values for `$publishProperties` use `Get-Help publish-aspnet –Examples`.
|
||||
* `$publishProperties` is a PowerShell hashtable which contains all the properties declared in the profile .pubxml file. It also includes values for file text replacements
|
||||
or files to exclude. For more info on the values for `$publishProperties` use `Get-Help publish-aspnet –Examples`.
|
||||
|
||||
To customize this process, you can edit the PowerShell script directly. To perform an action before publish starts, add the action before the call to `Publish-AspNet`. To have an action performed after publish, add the appropriate calls after Publish-AspNet. When Publish-AspNet is called the contents of the $packOutput directory are published to the destination. For example, if you need add a file to the publish process, just copy it to the correct location in `$packOutput` before `Publish-AspNet` is called. The snippet below shows how to do that.
|
||||
To customize this process, you can edit the PowerShell script directly. To perform an action before publish starts, add the action before the call to `Publish-AspNet`.
|
||||
To have an action performed after publish, add the appropriate calls after Publish-AspNet. When Publish-AspNet is called the contents of the $packOutput directory are
|
||||
published to the destination. For example, if you need add a file to the publish process, just copy it to the correct location in `$packOutput` before `Publish-AspNet`
|
||||
is called. The snippet below shows how to do that.
|
||||
|
||||
```powershell
|
||||
# copy files from image repo to the wwwroot\external-images folder
|
||||
|
|
@ -147,6 +181,9 @@ To customize this process, you can edit the PowerShell script directly. To perfo
|
|||
Publish-AspNet -publishProperties $publishProperties -packOutput $packOutput -pubProfilePath $pubProfilePath
|
||||
```
|
||||
|
||||
In this snippet external images are copied from `c:\resources\external-images to $packOutput\wwwroot\external-images`. Before starting the copy operation the script ensures that the destination folder exists. Since the copy operation takes place before the call to `Publish-AspNet` the new files will be included in the published content. To perform actions after the files have reached the destination then you can place those commands after the call to `Publish-AspNet`.
|
||||
In this snippet external images are copied from `c:\resources\external-images to $packOutput\wwwroot\external-images`. Before starting the copy operation the script ensures
|
||||
that the destination folder exists. Since the copy operation takes place before the call to `Publish-AspNet` the new files will be included in the published content.
|
||||
To perform actions after the files have reached the destination then you can place those commands after the call to `Publish-AspNet`.
|
||||
|
||||
You are free to customize, or even completely replace, the Publish-AspNet script provided. As previously mentioned, you will need to preserve the parameter declaration, but the rest is up to you.
|
||||
You are free to customize, or even completely replace, the Publish-AspNet script provided. As previously mentioned, you will need to preserve the parameter declaration,
|
||||
but the rest is up to you.
|
||||
|
|
|
|||
Loading…
Reference in New Issue