Deployment

  • Article

 

Microsoft Corporation
October 2003

Applies to:
    Microsoft® ASP.NET
    Microsoft Visual Studio® .NET
    Java Server Pages (JSP)

Summary: Learn about deployment methods made available by both JSP and ASP.NET. (9 printed pages)

Contents

Introduction
JSP Deployment Web Archives
WAR Structure
Generating WARs
Deploying WARs
CodeNotes Website Deployment
ASP.NET Deployment Microsoft Installer
Deployment Projects
Deploying the Application
Destination Server Requirements
Redeployment with XCopy
Summary

Introduction

In most cases, the machine on which you develop your Web applications will not be the same machine used to serve those applications over the Web. That is, you rarely spend time developing on your Web server. Therefore, you need to have some way of transferring your Web applications from one place to another without losing content or directory structure.

One way of doing this is to learn enough about the structure of Web applications in your particular language and manually copy all the files and directories from your development machine to the Web server. This will certainly work, provided that you know exactly what files need to be copied and that you know how to register or install the files at the other end. Sometimes this involves more than just cutting and pasting; with Microsoft® ASP.NET Web applications, for example, you will need to create a new virtual directory and register it under the IIS running on the Web server machine. Again, because IIS (and most other Web servers) require that Web applications be organized in a certain way, you must be very careful when doing this and you may need to edit other configuration files as well to ensure that all details point to the new location.

Obviously, there is an easier way. Both J2EE and Microsoft Visual Studio® .NET ship with utilities that allow you to compress Web resources and applications into archives that can then be copied to and unpacked on the destination machine with all their configurations and directory structures intact. In Java, this tool allows you to create Web Archives, or WAR files. (If you're not familiar with WARs, you will almost definitely be familiar with Java Archives (JARs). These contain Java class libraries, and you most likely had to include several of these in your system's CLASSPATH user variable before using J2EE.) Visual Studio .NET allows you to compress your Web projects into Microsoft Installer (MSI) files, which are basically self-extracting archives accompanied by an installer application that knows how to create virtual directories in IIS and register Web applications on the target machine.

xcopy is an MS-DOS® command that is used to copy files and directories. Because .NET assemblies, which house .NET Web applications, are self-describing, you will not need to register your .NET application using Microsoft Windows® utilities such as regsvr32.exe, which you previously had to do when deploying Windows applications. This makes it possible for most Web applications to be deployed by simply copying the files to the deployment directory and making a few changes to your IIS configuration. Unless your application requires assemblies to be installed in the target computer's Global Assembly Cache (in other words, you wish to only have a single copy of a library on the target system and the library is shared amongst multiple applications), or during the deployment of your Web application you wish to make changes to the configuration of the target machine (for example, if your Web application creates log files and you wish to create a desktop shortcut to editing these log files), you will most likely be able to deploy your application using xcopy.

Each of these three methods will be discussed and compared in this whitepaper.

JSP Deployment Web Archives

Deployment of Java Web applications (containing servlets and JSP code) is usually done using Web Archives, or WARs. WARs are very similar to JARs; where JARs contain class libraries or stand-alone applications, WARs contain JSP code, servlet classes, supporting classes, and other necessary files such as HTML documents and XML configuration files. Java Web applications can be compressed into WARs using a utility included with the J2EE and then copied to a Web server. Deployment of WARs is extremely straightforward, as the WAR can be deployed directly without even having to extract it first.

WAR Structure

The internal structure of a WAR matches the structure of a Web application, so that WARs may be created from existing Web applications without having to configure how files are mapped to different directories. The structure of a WAR is roughly as follows:

  • Root directory (top-level JSP, HTML, and other Web pages)
  • Subdirectories (sub-level JSP, HTML, and other Web pages; conforms to the page layout of the Web site)
  • \WEB-INF directory (hidden from the Web server; contains configuration and class files)
  • \WEB-INF\web.xml (deployment descriptor for servlets)
  • \WEB-INF\classes directory (holds servlet classes, JavaBeans, and other required classes for the Web applications)
  • \WEB-INF\lib directory (holds JAR class libraries required for included classes)

Note that the classes and lib directories are automatically included in the Web application's CLASSPATH when the WAR is deployed on a Web server.

Generating WARs

WARs are generated using the jar.exe utility. To create a WAR file containing your Web application, open a command prompt, change to the root directory of your Web application, and type the command shown in Listing 1.

Listing 1. Generating a WAR

jar cvf WARNAME.war

This will create a file named WARNAME.war in the root directory of your Web application. Obviously, you will want to use a file name more appropriate to your application. The options provided after the jar command are standard: c indicates that a new archive should be created, v indicates verbose output (you will see a list of the files as they are added), and f allows you to specify a file name for the generated archive. You can type jar without any parameters to see a list of other available options.

Deploying WARs

Once you have a WAR file, you can copy it to your Web server. Where you place the file depends on what Web server you are using, although in most cases you could place it almost anywhere and still create a reference to it in the server's configuration files. Most Web servers, however, have a default location in which Web applications are stored. In Tomcat 4.0, for example, you will find that WAR files for Web applications are all placed in C:\jakarta-tomcat-4.0.3\webapps. You will need to determine an appropriate location for your own server.

You then need to tell the Web server where to find the WAR file and how to access it. In Tomcat, this is done by adding a new<context>element to C:\jakarta-tomcat-4.0.3\conf\server.xml. We can do this using any text editor. The<context>element should look something like the one in Listing 2.

Listing 2. A <context> for a WAR file

<Context path="/APP_PATH"
   docBase="WARNAME.war"
   defaultSessionTimeOut="30" isWARExpanded="false"
   isWARValidated="false" isInvokerEnabled="true"
   isWorkDirPersistent="false" debug="0"
   reloadable="true" />

Most of the parameters in this context are standard, and you can find information about them in the Tomcat documentation. The three that you should take note of here are:

  • path, which indicates the virtual location of the application. For example, if our Web server was registered as www.codenotes.com, the context in Listing 2 would make the application available at http://www.codenotes.com/APP\_PATH.
  • docBase, which should contain the actual location of the WAR file. In Tomcat, this location is relative to the webapps directory.
  • isWARExpanded, which indicates whether or not the context refers to a WAR or a fully expanded set of directories. Since we are referring to a WAR in this case, this parameter should be set to false.

After you add this context, you will need to restart Tomcat. You will then be able to access any of the pages or servlets in your WAR file using a Web browser. For example, assuming you're still working with codenotes.com and you have a JSP in your archive named Hello.jsp , you could access it at http://www.codenotes.com/APP\_PATH/hello.jsp.

Note, as we said before, each Web server will have its own method of configuration for WAR files. In fact, many more complex servers come with special utilities that will place the WAR file in an appropriate location and configure the server settings for you so that you do not have to manually edit XML files. You should check your Web server documentation to find out whether your Web server has such a tool and how to use it.

CodeNotes Website Deployment

During the development of the CodeNotes site, we maintained a directory structure following the requirements for a WAR, as explained in "WAR structure". This made deploying the CodeNotes site very easy, as we were able to use Apache ANT, a build tool with functionality similar to the Unix-style make command, to create our WAR files. Apache ANT uses an XML file with various tags to specify actions to take. For example, a<WAR>element with its various attributes is used to specify the creation of a WAR file from the files located in a specific directory. This allowed us to create our WAR files at compile time without much extra effort. During development, we had configured our XML file to build all the classes. The ANT script is actually included in the Java source code for the Web site.

The CodeNotes ANT script actually builds two files. The first is the WAR file for deployment on the J2EE Web server. The second file is a zip file containing all of the sample code, images and other miscellaneous files that are not code-related. We could have combined these two files, however the "non-code" portion rarely changes, so deployment was simplified by separating the data into two pieces. Once we had the WAR file, we transferred it over to our Web server and then re-deployed the application on JRun, which required a server restart.

ASP.NET Deployment Microsoft Installer

For most Web application scenarios, creating an MSI file and deploying it to a destination server is straightforward and requires very little additional work. Unlike Java WARs, with which it is usually necessary to manually unzip the archive and change some configuration settings, the built in Windows installer application included in an MSI file does all the work for you. Deploying to a new server in ASP.NET can be as simple as creating a new project, dragging and dropping the applications you want to deploy into that project, building it, and running the MSI on the destination computer. In the sections that follow, we will demonstrate how to do all of these things.

Deployment Projects

Microsoft Installer files are generated as the output of a deployment project in Visual Studio .NET. Deployment projects are basically containers into which you place other existing projects. You can also modify some configuration options in deployment projects to make sure that the installed software will conform to the setup of the destination machine(s). When you build a deployment project, the MSI file will be created along with several other important files that we will discuss in a moment.

Creating a Deployment Project

To create a deployment project open Visual Studio .NET and click on New Project. In the Project Types list, select Setup and Deployment Projects. To create a Web deployment project that can be used to deploy ASP.NET Web applications, select the Web Setup Project icon from the templates list. Give your project a name (for instance, MyWebAppSetup) and click OK to create the project.

Adding Your Web Applications to the Deployment Project

If you create a deployment project as a new project, it will be empty, and the installer file generated if you build the project will not install anything. The main window of a deployment project shows the file system on the target machine (the directory structure that will be created when the MSI is run). In order to add Web applications to this file system, you must add your Web application projects to the same solution as the deployment project.

To add an existing project to your deployment project, right-click the Solution name at the top of the Solution Explorer window, and then click Add Existing Project. Locate the directory in which your Web application is stored, select it, and click OK. Note that if your Web application was created as its own solution, you may need to change the file type being looked for by using the dropdown list at the bottom of the Add Existing Project window. (By default, it looks for project files like *.csproj and *.vbproj rather than solution files, which end in .sln).

Regardless of whether you add a solution or a project, Visual Studio .NET will add a new project to your deployment project's solution. If you look in the Solution Explorer now, you will see both projects listed (along with all their references and dependencies).

To add your Web application to your deployment project's list of files to be installed, right-click the deployment project name in the Solution Explorer window, and then click Add Project Output. A window will appear, from which you can select the parts of the project you want to include in the installer.

Select the project you want to add from the drop-down list at the top of the window. Hold down the CTRL key and click only the components of the project you want to add to the MSI file. In many cases you will not want to include components such as Debug Symbols and Source Files as these are not generally made available to the public anyway.

Clicking OK will return you to the main Visual Studio .NET window, where you will now be able to see the components you added in the Solution Explorer.

Building the Deployment Project

You can now build your deployment solution by selecting Build MyWebAppSetup (where MyWebAppSetup is the name of your deployment project). Unless you have changed your configuration, the project will be built in My Documents\Visual Studio Projects\MyWebAppSetup. By default, the MSI file will be found in a folder under this one named Debug . Visual Studio .NET expects that you will want to test your installer before releasing it.

When you want to build a release version of your deployment project, you must change the project's configuration. Select the name of the deployment project in the Solution Explorer, and then click Build Configuration Manager. In the Active Solution Configuration drop-down list, change the value from Debug to Release, and then click Close. Now, when you build the project, your files will be created in the Release directory instead of the Debug directory.

What Are All These Files For?

You may have noticed that several other files are generated in addition to the MSI when you build a deployment project. Here are some brief descriptions of these files:

  • filename.msi is your Microsoft Installer file. This is actually all you need to install the application on the target machine, provided that machine is configured correctly.
  • Setup.Exe is a bootstrap application that, by default, simply executes the MSI application. As you will see in the next section, you can configure this file so that it also installs additional software or configuration files when necessary.
  • Setup.Ini is the configuration file for Setup.Exe. It contains information on what applications Setup.Exe is responsible for running.
  • InstMsiA.Exe and InstMsiW.Exe are install files for Windows Installer, the software required to run MSI files. InstMsiA.Exe should be run on Microsoft Windows 95, Windows 98, and Windows Me machines, and InstMsiW.Exe should be run on Microsoft Windows NT®, Windows 2000, and Windows XP machines that do not already have Windows Installer available. You may need to use one of these on your destination machine if you have trouble running your MSI files once you have copied them over.

Deploying the Application

To deploy the application, simply copy the MSI file, Setup.Exe, Setup.Ini , and any additional files to the destination computer, and then run Setup.Exe. The Windows Installer is a fairly typical Windows wizard application. The only decision you will need to make during installation is into what virtual directory you want to install the application, and on what port you want it to run.

The Installer will automatically create the virtual directory for this application, register it with IIS, and decompress the application files into the appropriate directory structure.

If you receive any errors when attempting to deploy your application, your destination machine may be missing some required software. See the next section of this document for details.

Destination Server Requirements

The server to which you deploy your ASP.NET Web application requires three pieces of software in order for the application to run correctly:

  • IIS 5.0 or later (and therefore Windows 2000 or Windows XP, since IIS 5.0 will not run on earlier versions)
  • Windows Installer (which you can install using either MsiInstA.Exe or MsiInstW.Exe, as discussed in the previous section of this document)
  • The .NET Framework

The last of these may present some difficulty, because while your development machine already has the .NET Framework installed, your Web server may not. There are several ways in which you can make sure the machine to which you install your Web applications has the .NET Framework installed.

Installing the .NET Framework Manually

If you or one of your co-workers are using the MSI files simply to move your Web applications safely from one machine to another, the best solution for putting the .NET Framework on the Web server is probably just to do it manually. The .NET Framework Redistributable Package (Dotnetfx.exe ) is located on your Microsoft Visual Studio .NET Windows Component Update CD dotNetFramework directory. Alternatively, you can download Dotnetfx.exe from the Microsoft Download Center.

To use this file, simply copy it to the machine on which you want to install the .NET Framework, and then run it. Follow the instructions to complete the installation, and you will then be able to deploy your Web applications safely.

Using the Setup.exe Bootstrapper Sample

The Setup.exe Bootstrapper sample is a Setup application you can use to replace the one automatically generated when you compile your deployment application. When run, this application checks to see whether the version of the .NET Framework currently installed on the target machine matches the one used to develop the application (or whether it exists at all). If the versions do not match, the application installs the newer Framework. It then proceeds to run the MSI file and deploy your application.

To make use of this replacement Setup application, you first need to tell your deployment project not to create its own Setup application. Open the project in Visual Studio .NET and select Project Properties. In the Bootstrapper drop-down box, change the value from Windows Installer Bootstrapper to None. Click OK, and then rebuild the project. Note that if you have built the project previously, you will want to delete the generated files before rebuilding. Building a project with no bootstrapper selected should generate an MSI file and nothing else.

To use the Bootstrapper, you need to download bootstrapper_sample.exe from the Microsoft Download Center. This is a self-extracting executable, and will produce two files when run: Setup.exe and Setup.ini. Place these in the same directory as your MSI file.

You will also need to obtain the .NET Framework Redistributable Package (Dotnetfx.exe), as detailed in the previous section. Place Dotnetfx.exe in the same directory as your MSI and the Bootstrapper sample files. These four files (Setup.exe , Setup.ini, Dotnetfx.exe , and your MSI file) constitute your new installation package.

Before copying these files to the destination machine, you need to make several changes to Setup.ini. Open Setup.ini in a text editor and change the following lines:

  • Msi=FxCopSourceSetup.msi should be changed to Msi=YourMSIFile.msi.
  • 'FxInstallerPath=c: should be uncommented (remove the apostrophe) and changed to reflect the location of Dotnetfx.exe . For example, if Dotnetfx.exe is in the current directory, this line can beFxInstallerPath=.(including the period). If you wish to store Dotnetfx.exe separately from your other installation files (for instance, in a more publicly accessible location like on a network), this line should reflect its true location.

You can now copy your MSI file and the two Setup files to the Web server and run Setup.exe. If necessary, the .NET Framework will be installed or upgraded on the target machine, and then the MSI file will be run to install your Web application(s).

Redeployment with Xcopy

Because of the way ASP.NET works, once you have deployed your application the first time, a re-deployment is as simple as copying the files over to the server. You do not need to run the MSI again or shut down your existing server. ASP.NET will recognize that files have changed and will automatically create a new "workspace" for the revised application. Any new user sessions will automatically be directed to the new workspace, while any existing sessions will continue against the old workspace. In this fashion, you have a smooth transition from old code to new code without disrupting your service.

In other words, once you've deployed the first time (to establish the directory and settings), you can re-deploy simply by copying your application files over to the server and replacing the existing files. You do not need to recreate a deployment package or restart the server, or work through any GUI wizard, just simply copy over the files.

Summary

Deployment of JSP Web applications is quite different from deployment of ASP.NET applications. JSP applications are packaged into Web Archive (WAR) files that must then be copied to the Web server. The Web server can directly reference WAR files, and there is no need to extract them back into directories and files in order to deploy them.

ASP.NET applications, on the other hand, are best deployed using a Visual Studio Deployment Project. ASP.NET Web application projects are added to deployment projects, which are then built as though they were normal applications. The output of these projects is a Microsoft Installer (MSI) file, which can be copied to the destination machine and run to extract the files back into their original directory structure and register the application and virtual directory on that machines IIS Web server. Deploying applications in this way requires that the target machine have IIS 5.0, Windows Installer software, and the .NET Framework installed.

As we have seen in this document, the deployment methods made available by both languages are far safer and easier than manually copying files and directories and registering them in new locations. When migrating your applications from JSP to ASP.NET, you should consider how your application will be packaged and how this affects your overall deployment plans when compared to your previous experience with JSP.

© Microsoft Corporation. All rights reserved.