Building ClickOnce Applications from the Command Line
In Visual Studio, you can build projects from the command line, even if they are 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 allows you to reproduce a build using an automated process, for example, in a central build lab or using advanced scripting techniques beyond the scope of building the project itself.
Using MSBuild to Reproduce ClickOnce Application Deployments
When you invoke msbuild /target:publish at the command line, it tells the MSBuild system to build the project and create a ClickOnce application in the publish folder. This 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 achieve that by typing msbuild. This command works because the build target is the default target for all projects generated by Visual Studio. This means you do not explicitly need to specify the build target. Therefore, typing msbuild is the same operation as typing msbuild /target:build.
The /target:publish command tells MSBuild to invoke the publish target. The publish target depends on the build target. This means that the publish operation is a superset of the build operation. For example, if you made a change to one of your Visual Basic or C# source files, the corresponding assembly would automatically be rebuilt by the publish operation.
For information on generating a full ClickOnce deployment using the Mage.exe command-line tool to create your ClickOnce manifest, see Walkthrough: Manually Deploying a ClickOnce Application.
Creating and Building a Basic ClickOnce Application Using MSBuild
To create and publish a ClickOnce project
Click New Project from the File menu. The New Project dialog box appears.
Select Windows Application and name it CmdLineDemo.
From the Build menu, click the Publish command.
This step ensures that the project is properly configured to produce a ClickOnce application deployment.
The Publish Wizard appears.
In the Publish Wizard, click Finish.
Visual Studio generates and displays the default Web page, called Publish.htm.
Save your project, and make note of the folder location in which it is stored.
The steps above create a ClickOnce project which has been published for the first time. Now you can reproduce the build outside of the IDE.
To reproduce the build from the command line
Exit Visual Studio.
From the Windows Start menu, click All Programs, then Microsoft Visual Studio 2008, then Visual Studio Tools, then Visual Studio 2008 Command Prompt. This should open a command prompt in the root folder of the current user.
In the Visual Studio 2008 Command Prompt, change the current directory to the location of the project you just built above. For example, type chdir My Documents\Visual Studio\Projects\CmdLineDemo.
To remove the existing files produced in "To create and publish a ClickOnce project," type rmdir /s publish.
This step is optional, but it ensures that the new files were all produced by the command-line build.
Type msbuild /target:publish.
The above steps will 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 redistributables for the .NET Framework. This is the entire set of files you need to deploy your application over the Web or via UNC or CD/DVD.
Publishing Properties
When you publish the application in the above 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>https://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>
You can override any of these properties at the command line without altering the project file itself. For example, the following will build 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. Below is a description of the publishing properties, along with an indication of how each is set in the various property pages of the application designer:
- AssemblyOriginatorKeyFile determines the key file used to sign your ClickOnce application manifests. This same key may 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 will automatically turn this flag on 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 will 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 is 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 will be published to in the IDE. It is inserted into the ClickOnce application manifest if neither the InstallUrl or UpdateUrl property is specified.
ApplicationVersion specifies the version of the ClickOnce application. This is a four-digit version number. If the last digit is a "*", then the ApplicationRevision is substituted for the value inserted into the manifest at build time.
ApplicationRevision specifies the revision. This is an integer which increments each time you publish in the IDE. Notice that it is not 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 will install the application from. If specified, this value is burned into the setup.exe bootstrapper if the IsWebBootstrapper property is enabled. It is also inserted into the application manifest if the UpdateUrl is not 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 will receive 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. In the case of an installed application, it is 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. In the case of an installed application, it is 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.
InstallURL, SupportUrl, PublishURL, and UpdateURL
The following table shows the four URL options for ClickOnce deployment.
URL option |
Description |
|---|---|
PublishURL |
Required if you are publishing your 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. |
See Also
Tasks
Walkthrough: Manually Deploying a ClickOnce Application