Deploying Services with Web Deploy

RELATED: "Open Source AJAX App Development and Deployment Solution" and "Manage Staging Deployments in Microsoft Windows Azure."

Deployment is a step in the software development process that every service experiences, moving from development to test, test to production, and so on. Until now, deployment has received minimal support, with most deployments ultimately a mixture of batch scripts and manual configuration. As the complexity of the systems that can be built for the Windows Server Web Platform increase, so does the complexity to deploy them, thus the need to minimize human error and increase deployment efficiency via automation. This is where Web Deploy, officially called the Web Deployment Tool and sometimes known as MS Deploy, shines.

Introducing Web Deploy

Web Deploy is feature rich. It's an extension to IIS, a component in Visual Studio 2010, a command line executable, and a managed framework for deploying complete servers, web sites and, web applications. Web Deploy supports deployment from development to test in two ways. In a process referred to as packaging, Web Deploy will wrap up your Visual Studio Web or Service Applications into a single zip file that contains all relevant files and configuration (see Figure 1). This zip file, referred to as a package, is then painlessly imported on the target server through IIS Manager and results in a website that is ready to run.

Figure 1: Creating a package from the context menu of a project in VS2010 solution explorer. Click to expand.

Alternately, Web Deploy can deploy directly to the target server from Visual Studio 2010 via a process referred to as publishing, as shown in Figure 2. Once a profile is defined, the Web One Click Publish toolbar can be used to quickly re-publish an application (see Figure 3). In addition to supporting a fresh deployment, Web Deploy gracefully handles the updating of sites previously deployed, whether you deploy with packaging or publishing.

Figure 2: Publishing from Visual Studio 2010.

Figure 3: The Web One-Click Publish toolbar.

Once deployed to an IIS server, Web Deploy supports the importing of packages through IIS Manager (Figure 4) or the command line, which lets you perform migrations between servers or set up duplicate configurations between nodes in a web farm. There are often post-deployment configuration changes that are performed directly on the server, and Web Deploy's export functions allow you to captures these changes into a package for redeployment of the final configuration to other servers.

Figure 4: Import & Export for an application available at the website level in IIS Manager. Click to expand.

Web Deploy Setup

Web Deploy is free and easy to set up. If you've installed Visual Studio 2010 Beta 2, then a typical installation of Web Deploy is already installed. You can also download it for other machines. The installer is about 5MB and installation takes less than thirty seconds.

The setup provides a choice of Typical, Complete, or Custom setup types to determine which features (of IIS Manger UI Module, IIS 7 Deployment Handler, Management Service Delegation, and the Remote Agent Service) are installed. For most scenarios, I suggest you perform a Complete install, because this will enable your server for remote deployment. The remote support is provided by a combination of the Web Deployment Agent Service and the Web Management Service, which must both be started manually and set to start automatically after the installation (by default, they're set to start manually and are stopped).

If you want to use the remote features on your dev box where Visual Studio 2010 installed Web Deploy, run the Web Deploy setup to change the installed features. Install all the features and remember to start the two services after installation. This will let you, for example, use the Web One-Click Publish against your local development machine.

Creating a Package in Visual Studio

Most deployment procedures begin with a deployment from the development environment to another location. To show how to use Web Deploy, I'll first show a new WCF Workflow Service Application called DemoDeployment. To keep things simple, I'll just use the application as created from the project template.

Right-clicking the DemoDeployment project in Solution Explorer will show the Create Package menu option, as was shown in Figure 1. Clicking Create Package will kick off the package creation process. By default, the package is created in the objDebugPackage directory of the project (assuming you are using a Debug build configuration) and is named after the project.

If you navigate to this directory, you'll see some files in addition to the ZIP. These files let you import from the command line by executing the provided CMD file, which wraps a call to the Web Deployment tool MSDeploy.exe. Normally, during an Import performed using IIS Manager (described next) a dialog is displayed allowing you to configure parameters for the import (such as connection string values, web application name or physical path). The *.SetParameters.xml file allows you to provide these parameters to the CMD file. Opening the one generated for my DemoDeployment package shows the parameter that Visual Studio automatically configured: the IIS Web Application Name (see Figure 5). Simply running this CMD file from the command line with the /Y switch will import the package into the local IIS instance.

Figure 5: Contents of DemoDeployment.SetParameters.xml. Click to expand.

Importing a Package with IIS Manager

Now that I have my package, DemoDeployment.zip, I can import it into IIS using IIS Manager. Open IIS Manager and expand the connections node until you see the website into which you want to import the application (in my case, I'm using Default Website). Right-click the Default Website node and select Deploy, Import Application. On the first screen (Figure 6), browse to the package and click Next. The next screen (Figure 7) allows you to choose what content of the package to import and configure additional settings. If you want everything, just click Next. After that, the Enter Application Package Information screen allows you to specify the values for any parameters defined in the package (for example, connection strings). The parameter values are pre-initialized with the values stored in the package. In my case, by Visual Studio when I created the package. Recall from Figure 5 that I had a parameter for the IIS Web Application Name. Notice in Figure 8 how Web Deploy restricts me to modifying the application path below Default Web Site, because I started this import from the context of Default Web Site and I'm importing an Application Package. When a package defines additional parameters, this screen allows editing of them as well.

Figure 6: Choosing the application package to import. Click to expand.

Figure 7: Selecting what parts of the package to import. Click to expand.

Figure 8: Configuring package parameter values. Click to expand.

After clicking Finish (Figure 9), you should see the new application added under Default Web Site in IIS Manager and be able to browse to the service helper page for Service1.xamlx using a web browser.

Figure 9: Import process results.

Publishing from Visual Studio 2010

The Create Package/Import Package procedure just illustrated is useful when you need to hand off the deployment files for someone else to import. However, if you have access to the target server and have performed a complete installation of Web Deploy on it, you can perform a similar deployment directly from Visual Studio 2010 using the Publish feature and the One-Click Web Publishing toolbar. To do this, right click on the project you want to publish (again, in my case I'll use the DemoDeployment project) and choose Publish…, as shown in Figure 10. This will bring up the Publish Web dialog shown in Figure 2. The purpose of this dialog is twofold—to allow you to define all of the settings necessary to deploy to the target server and save those settings in a profile you name, and to allow you publish according to those settings.

Figure 10: Publishing from Solution Explorer. Click to expand.

To use Web Deploy, the Publish Method must be set to MSDeploy Publish. The Service URL can be the name of your target server, if on the same LAN, or the address of the server (usually specified when your publishing to a 3rd party hosting provider). For the Site/Application you need to specify the website and application name. You will want to check the Mark as IIS application on destination, to ensure your service project is created as an application and not just a virtual directory. Depending on your particular scenario, you may opt to uncheck the Do not delete extra files on destination if you want to ensure that during an update (caused simply by re-running the publish procedure) the application deployed contains only the files in the package and not any other ones that might have been added on the target server. Unless your server has a production certificate configured, you'll want to check the Allow Untrusted Certificate. By default Web Deploy will install and rely on a self-signed certificate. Finally, specify the username and password of a user (usually an administrator) allowed to perform deployments. If you don't specify an account, when you click Publish a subsequent dialog will prompt you for the credentials.

Finally, click Publish. This will save your profile and kick off the Publish process. You'll know that the publishing succeeded if you see the words "Publish succeeded" in the bottom left hand side of Visual Studio. If it fails, the error message will appear in the Error List window.

Now that you have a successful initial publication, you can use the Web One-Click Publish toolbar (Figure 3) to perform the publish according to the profile selected in the drop down. You can also bring up the profile editing dialog from the toolbar by clicking the Edit Publish Profiles button.

Exporting from IIS Manager

Either of the two aforementioned procedures serves to get a web application or service application installed in IIS. Web Deploy also provides functionality for exporting either an entire server or an individual application to a package. Continuing with my DemoDeployment example, I can create a package for the DemoDeployment application by right-clicking it in the Connections tree view of IIS Manager and selecting Deploy, Export Application....

This will bring up the Export Application Package wizard, and in the first screen you choose what contents to include in the package (Figure 11). This dialog is very similar to the one shown during import except that it also allows you configure providers by clicking the Manage Components… button (Figure 12). Providers are commonly used to create web applications (the iisApp provider is responsible for the Web Application in this case) and also allow you to define steps the import process needs to take such as deploying a SQL database, creating directories, GAC assemblies, setting ACL's or running a command line executable. For a list of the available providers and their properties, see this Microsoft article.

Figure 11: Configuring contents of exported application package. Click to expand.

Figure 12: Adding a provider. Click to expand.

Within the Manage Components window, click the Provider Settings cell to the right of the provider you want to configure to bring up a property grid that allows you set values of the provider-specific properties. When added, these providers will appear in the tree view as part of the package contents, in the order in which they appear in the Manage Components screen (which affects the order in which they are applied at deployment time).

Click again to display the Select Parameters screen, which allows you to configure the parameters of your packages. The next screen allows you to specify the path where you want the zip file created. This is followed by a screen showing the package creation progress, and finally the Export Progress and Summary screen, which details the results of the export.

Additional Package Configuration

You may have noticed Package/Publish Settings menu item in Figure 10. Clicking this will take you to the project properties, Package/Publish tab, and allow you to configure the various package provider settings (see Figure 13). Most of the settings are self-explanatory.

Figure 13: Package/Publish project settings. Click to expand.

Notice in the figure how the check boxes for "Include all IIS settings for this web project as configured in IIS Manager" and its child "Include Application Pool settings used by this web" are disabled. Visual Studio is able to direct a package export using Web Deploy from IIS that includes IIS Settings (such as default files, application pool configuration, etc.) just as if you had performed the export from IIS Manager manually. In order to use this, the project must be associated with a Virtual Directory in IIS. To do this, click the Web tab in the project properties. In the Servers section, change the selected radio button from Use Visual Studio Development Server to Use Local IIS Web Server and click the Create Virtual Directory button (Visual Studio must be running with administrator privileges for this). Now if you return to the Package/Publish tab, the ability to select Include all IIS Settings will be enabled, and checking it will enable Include Application Pool settings.

Notice that in Figure 13, Include all Databases configured in Deploy SQL Tab is checked. By checking this box, you're enabling the inclusion of SQL deployment scripts in your package. Clicking the Deploy SQL tab brings up the properties screen through which you configure the connections strings to parameterize in the package, the source database for schema and/or data or a sql script which creates the schema and/or data. It is useful to note that this dialog supports configuring a source database used for the data only with a script file added that creates the schema. These will be pulled into the package as SQL scripts and executed during an Import. The Destination Database connection string need not be specified as the Import wizard will prompt for it during the import, but it can be handy to specify if the actual value is known in advance.

This article is a broad overview of the functionality provided by Web Deploy in support of deploying services from Visual Studio 2010 to an IIS instance and between IIS instances.