Edit

Build ClickOnce applications from the command line

  • Article

In Visual Studio, you can build projects from the command line, even if they're created in the integrated development environment (IDE). In fact, you can rebuild a project created with Visual Studio on another computer that has only the .NET Framework installed. This capability allows you to reproduce a build by using an automated process, for example, in a central build lab or with advanced scripting techniques beyond the scope of building the project itself.

Note

To build .NET ClickOnce applications from the command line, see Build .NET ClickOnce applications from the command line.

Use MSBuild to reproduce .NET Framework ClickOnce application deployments

When you invoke msbuild /target:publish at the command line, this command instructs the MSBuild system to build the project and create a ClickOnce application in the publish folder. This command is equivalent to selecting the Publish command in the IDE.

This command executes msbuild.exe, which is on the path in the Visual Studio command-prompt environment.

A "target" is an indicator to MSBuild on how to process the command. The key targets are the "build" target and the "publish" target. The build target is the equivalent to selecting the Build command (or pressing F5) in the IDE. If you only want to build your project, you can enter msbuild. This command works because the build target is the default target for all projects generated by Visual Studio. As a result, you don't need to explicitly specify the build target. Therefore, entering msbuild is the same operation as entering msbuild /target:build.

The /target:publish command tells MSBuild to invoke the publish target. The publish target depends on the build target, which means that the publish operation is a superset of the build operation. For example, if you made a change to Visual Basic or C# source files, the publish operation automatically rebuilds the corresponding assembly.

For information on generating a full ClickOnce deployment by using the Mage.exe command-line tool to create your ClickOnce manifest, see Walkthrough: Manually deploy a ClickOnce application.

Create and build a basic ClickOnce application with MSBuild

The easiest way to create a publish profile is by using Visual Studio. A publish profile is required to publish with MSBuild.

Create and publish a ClickOnce project

  1. Open Visual Studio and create a new project.

    Choose the Windows Forms App (.NET Framework) or WPF App (.NET Framework) project template and name the project CmdLineDemo.

  2. From the Build menu, select the Publish command.

    This step ensures that the project is properly configured to produce a ClickOnce application deployment.

    The Publish Wizard appears.

  3. In the Publish Wizard, select Finish.

    Visual Studio generates and displays the default web page, called Publish.htm.

  4. Save your project, and make note of the folder location in which it's stored.

    The preceding steps create a ClickOnce project that's been published for the first time. Now you can reproduce the build outside of the IDE.

Reproduce the build from the command line

  1. Exit Visual Studio.

  2. From the Windows Start menu, select Tools > Command line > Developer Command Prompt.

    The Visual Studio Developer Command Prompt opens.

  3. In the Visual Studio Command Prompt, make sure the current directory shows the location of the project you built previously.

    If you're not working in the project directory, enter a command to change to the desired location, such as chdir C:\Users\username\source\repos\CmdLineDemo.

  4. To remove the existing files produced in the previous section, enter rmdir /s publish.

    This step is optional, but it ensures the command-line build produces all the new files.

  5. Enter msbuild /target:publish.

    The preceding steps produce a full ClickOnce application deployment in a subfolder of your project named Publish. CmdLineDemo.application is the ClickOnce deployment manifest. The folder CmdLineDemo_1.0.0.0 contains the files CmdLineDemo.exe and CmdLineDemo.exe.manifest, the ClickOnce application manifest. Setup.exe is the bootstrapper, which by default is configured to install the .NET Framework. The DotNetFX folder contains the redistributable files for the .NET Framework. The files in this location comprise the entire set of files you need to deploy your application over the web or via UNC or CD/DVD.

Note

The MSBuild system uses the PublishDir option to specify the location for output, such as msbuild /t:publish /p:PublishDir="<specific location>".

Publish process output

MSBuild uses the PublishDir property to set the build output location, including build artifacts. The PublishDir value that MSBuild uses as the destination for the publish is obtained by default from the PublishDir property in the project file (.NET Framework). You can override this behavior on the MSBuild command line by using the /p switch. If you override the setting, the publish output goes to the location specified. The output is generated during the MSBuild step of publish. Any MSBuild target with AfterTargets="ClickOncePublish" runs after this copy is made.

The PublishUrl property, unlike PublishDir, isn't used in the MSBuild step. PublishUrl is ignored when you invoke MSBuild directly to publish from the command line.

When Publishing is started in Visual Studio IDE, Visual Studio invokes MSBuild to publish artifacts into the PublishDir location. After this MSBuild step completes, Visual Studio then publishes ClickOnce-specific files to the location pointed to by PublishUrl. This second step runs inside the Visual Studio process. You can't inject any target/task to run during this step because it's a Visual Studio process.

For MSBuild deployments that don't use Visual Studio, copy all of the files in the deployment directory to the deployment destination or media. The deployment directory can be either a folder on a web site or FTP site, a file share, or a CD-ROM. For example, you might use a third-party tool or a custom MSBuild task to copy the ClickOnce files.

For any post-processing in the PublishUrl folder, you need to have a separate script.

Important

If PublishDir is set to the same location as PublishUrl, duplicate compilation output gets copied to the PublishUrl location. You can avoid this issue in Visual Studio 2022 version 17.4 and later by creating a new profile. The new profile sets PublishDir to a different location than PublishUrl. At the end of the publish operation, the relevant ClickOnce files are copied from the PublishDir to PublishUrl location.

Publish properties

When you publish the application by using the previous procedures, the following properties are inserted into your project file by the Publish Wizard. These properties directly influence how the ClickOnce application is produced.

In CmdLineDemo.vbproj / CmdLineDemo.csproj:

<AssemblyOriginatorKeyFile>WindowsApplication3.snk</AssemblyOriginatorKeyFile>
<GenerateManifests>true</GenerateManifests>
<TargetZone>LocalIntranet</TargetZone>
<PublisherName>Microsoft</PublisherName>
<ProductName>CmdLineDemo</ProductName>
<PublishUrl>http://localhost/CmdLineDemo</PublishUrl>
<Install>true</Install>
<ApplicationVersion>1.0.0.*</ApplicationVersion>
<ApplicationRevision>1</ApplicationRevision>
<UpdateEnabled>true</UpdateEnabled>
<UpdateRequired>false</UpdateRequired>
<UpdateMode>Foreground</UpdateMode>
<UpdateInterval>7</UpdateInterval>
<UpdateIntervalUnits>Days</UpdateIntervalUnits>
<UpdateUrlEnabled>false</UpdateUrlEnabled>
<IsWebBootstrapper>true</IsWebBootstrapper>
<BootstrapperEnabled>true</BootstrapperEnabled>

For .NET Framework projects, you can override these properties at the command line without altering the project file itself. For example, the following code builds the ClickOnce application deployment without the bootstrapper:

msbuild /target:publish /property:BootstrapperEnabled=false

Publishing properties are controlled in Visual Studio from the Publish, Security, and Signing property pages of the Project Designer.

The following publishing properties are set in various property pages of the application designer.

  • AssemblyOriginatorKeyFile determines the key file used to sign your ClickOnce application manifests. This same key might also be used to assign a strong name to your assemblies. This property is set on the Signing page of the Project Designer.

The following properties are set on the Security page:

  • Enable ClickOnce Security Settings determines whether ClickOnce manifests are generated. When a project is initially created, ClickOnce manifest generation is off by default. The wizard automatically turns on this flag when you publish for the first time.

  • TargetZone determines the level of trust to be emitted into your ClickOnce application manifest. Possible values are "Internet," "LocalIntranet," and "Custom." Internet and LocalIntranet cause a default permission set to be emitted into your ClickOnce application manifest. LocalIntranet is the default, and it basically means full trust. Custom specifies that only the permissions explicitly specified in the base app.manifest file are to be emitted into the ClickOnce application manifest. The app.manifest file is a partial manifest file that contains just the trust information definitions. It's a hidden file, automatically added to your project when you configure permissions on the Security page.

The following properties are set on the Publish page:

  • PublishUrl is the location where the application is published to in the IDE. It's inserted into the ClickOnce application manifest if both the InstallUrl and UpdateUrl property aren't specified.

  • ApplicationVersion specifies the version of the ClickOnce application. The version is a four-digit number. If the last digit is a "*" (asterisk), then the ApplicationRevision is substituted for the value inserted into the manifest at build time.

  • ApplicationRevision specifies the revision. This value is an integer, which increments each time you publish in the IDE. Notice that it isn't automatically incremented for builds performed at the command-line.

  • Install determines whether the application is an installed application or a run-from-Web application.

  • InstallUrl (not shown) is the location where users install the application from. If specified, this value is burned into the setup.exe bootstrapper if the IsWebBootstrapper property is enabled. It's also inserted into the application manifest if the UpdateUrl isn't specified.

  • SupportUrl (not shown) is the location linked in the Add/Remove Programs dialog box for an installed application.

The following properties are set in the Application Updates dialog box, accessed from the Publish page.

  • UpdateEnabled indicates whether the application should check for updates.

  • UpdateMode specifies either Foreground updates or Background updates.

  • UpdateInterval specifies how frequently the application should check for updates.

  • UpdateIntervalUnits specifies whether the UpdateInterval value is in units of hours, days, or weeks.

  • UpdateUrl (not shown) is the location from which the application receives updates. If specified, this value is inserted into the application manifest.

The following properties are set in the Publish Options dialog box, accessed from the Publish page.

  • PublisherName specifies the name of the publisher displayed in the prompt shown when installing or running the application. For an installed application, it's also used to specify the folder name on the Start menu.

  • ProductName specifies the name of the product displayed in the prompt shown when installing or running the application. For an installed application, it's also used to specify the shortcut name on the Start menu.

The following properties are set in the Prerequisites dialog box, accessed from the Publish page.

  • BootstrapperEnabled determines whether to generate the setup.exe bootstrapper.

  • IsWebBootstrapper determines whether the setup.exe bootstrapper works over the Web or in disk-based mode.

Use options: InstallURL, SupportUrl, PublishURL, UpdateURL

The following table shows the four URL options for ClickOnce deployment.

URL option Description
PublishURL Required to publish the ClickOnce application to a web site.
InstallURL Optional. Set this URL option if the installation site is different than the PublishURL. For example, you could set the PublishURL to an FTP path and set the InstallURL to a web URL.
SupportURL Optional. Set this URL option if the support site is different than the PublishURL. For example, you could set the SupportURL to your company's customer support web site.
UpdateURL Optional. Set this URL option if the update location is different than the InstallURL. For example, you could set the PublishURL to an FTP path and set the UpdateURL to a web URL.

Related content