John Allen and J.D. Meier

Using the Package and Deployment Wizard

rying to deploy your Visual Basic®-based applications using the Package and Deployment Wizard (PDW) can be a challenging experience. WebClasses are no exception. In fact, deploying WebClasses over the Internet introduces an additional layer of complexity. Successfully deploying WebClasses via the Internet using the PDW means that Visual Basic has hidden the complexities of the process from you—this can get in the way of diagnosing problems. We will provide an overview of the deployment process along with specific steps to help you deploy your WebClasses to your target server. Deployment in a Nutshell       Deploying a WebClass involves sending a CAB file to your Web server. When you run the PDW from your development machine, it sends your CAB file over the wire to Microsoft® Internet Information Server (IIS), and posts it to an isapi extension built in accordance with RFC 1867. At the Web publishing site, the Posting Acceptor (cpshost.dll) receives your CAB file, unpacks it, and registers your files.       During this process, there is a fair amount of communication between your client machine and the Web server. First, the client performs a GET request for the default document on the Web server's root directory. Next, the server may try authenticating the client. If authentication succeeds and the account has appropriate access, the server returns an HTTP status code of 200 "OK."       After authenticating, the server returns the HTTP status code 304 "Not Modified," along with the location of the default document. If the default document contains a <META> tag pointing to the \scripts directory, the client performs another GET request for the PostInfo.asp file. The server may again authenticate before sending the HTTP status code 200 "OK."       Finally, the client sends a POST request—using the same credentials, since it's within the same directory as the PostInfo.asp page. The client then begins the file transmission to the Web server, communicating with the Posting Acceptor. The Posting Acceptor, in turn, chunks the data to a temporary file within the C:\temp directory. If the upload succeeds, the Posting Acceptor then moves the temporary file to the deployment directory.       As you can see, there are a number of places where this process can break down. Security underlies a number of the potential problems. Since IIS security is mentioned throughout this article, we'll first provide a quick briefing on how it works. IIS Security       IIS provides three authentication settings: Allow Anonymous Access, Basic Authentication, and Windows NT Challenge/Response.       If you use the Allow Anonymous Access authentication setting, when a user attempts to connect to your Web server, the server assigns the user a Windows NT anonymous (or guest) user account. This account typically has security restrictions that determine the level of access available to users. When IIS is first installed, it creates a default anonymous account called IUSR_computername, where computername is the name of your Web server. Alternatively, you can specify your own custom anonymous account.       If you've enabled Basic Authentication, when a user attempts to connect to your Web server it will prompt the user for a valid Windows NT account user name and password. Your Web server will use Basic Authentication under the following conditions: Anonymous access is disabled. Anonymous access is denied because Windows NT permissions have been set to restrict access by the anonymous account.       With Windows NT Challenge/Response authentication, when a user attempts to connect to your Web server, your server engages in a cryptographic information exchange with the user's Microsoft Internet Explorer Web browser. The Web browser does not send actual Windows NT account password information across the network. Currently, only Internet Explorer 2.0 or later supports this authentication method. Your Web server will use Windows NT Challenge/Response authentication under the following conditions: Anonymous access is disabled. Anonymous access is denied because Windows NT permissions have been set to restrict access by the anonymous account.       These authentication methods are selected through the Internet Service Manager using the Microsoft Management Console (see Figure 1). To access this dialog, right-click on the desired Web directory or file within the Internet Service Manager and select Properties. Next, click the Directory Security tab or the File Security tab, and then click the Edit button within the Anonymous Access and Authentication Control section.

Figure 1: Setting Authentication

Before we dive too deep into the deployment process, we want to warn you of a few limitations of the PDW. First, when deploying a WebClass, your Web site must be running on port 80. Second, Windows NT Workstation does not support the use of the "Unpack and install server-side cab" option. Third, in order to use the "Unpack and install server-side cab" option, you must have Posting Acceptor 2.0 installed. Earlier versions of the Posting Acceptor do not support this option. Installing Posting Acceptor 2.0       If you need to verify whether you have Posting Acceptor 2.0 installed on your Web server, you can check Add/Remove Programs in the Control Panel. You should see a Microsoft Posting Acceptor 2.0 entry in the list of installed programs. If you do not see this entry, or it is not version 2.0, you will need to install Posting Acceptor 2.0. If you have an existing version of the Posting Acceptor, you should remove it using Add/Remove Programs before installing the updated version. The setup file for Posting Acceptor 2.0 can be found in a number of Microsoft products (see Figure 2). However, the Windows NT Option Pack 4.0 setup does not install version 2.0 of this package. Configuring the Server       Let's walk through the process of configuring your Web server for deployment. This process does not require making many configuration changes; you will mostly be verifying the default values. Consider this more of a checklist because your Web server should already be configured properly by default. However, while your default Web site may already be configured properly, your virtual servers will likely need some of these configurations applied.

Figure 3: Specifying a Default Document

First, you will need to verify that you have a default document specified. The PDW looks for the default document and searches the first line for a special <META> tag that tells it where the PostInfo.asp file is located. Open the Service Manager and select the Web site you are configuring for deployment. Right-click on the Web site and select Properties. Once the Properties window appears, select the Documents tab (see Figure 3). Make sure the Enable Default Document option is selected. If you do not see any documents in the list, you will need to create a default.htm file. If you see multiple documents in the list, take note of the first one. Open this file in Notepad and verify that it has the following <META> tag on the first line:

<META name="postinfo" content="/scripts/postinfo.asp">

If your default document does not have this <META> tag, you will need to add it. You should also open Windows® Explorer at this point and confirm that the PostInfo.asp and cpshost.dll files exist in the C:\InetPub\scripts directory (or in the appropriate directory for your setup).

Figure 4: Scripts Virtual Directory

Next, you need to have a ..\scripts virtual directory with execute permissions. Open the Internet Services Manager and expand the tree to show the directories beneath the Web site that you are configuring for deployment. Confirm that you have a virtual directory called scripts that points to the physical directory C:\InetPub\scripts. If this virtual directory already exists, you will need to verify that Execute permissions are enabled. Right-click on the scripts virtual directory and select Properties. In the Virtual Directory tab verify that the "Execute (including script)" option is selected (see Figure 4). If you do not see a scripts virtual directory, you will need to create it. To create this directory, right-click on your Web site and select New | Virtual Directory. Enter "scripts" for the Alias, click Next, and then browse to your C:\InetPub\scripts directory and click Next again. Make sure that the "Allow Execute Access (includes Script Access)" option is selected and click Finish.       Using Windows Explorer, confirm that the NTFS permissions for the C:\InetPub\scripts physical directory are set to read and execute (RX) for the appropriate Windows NT accounts. Remember, if you are using anonymous access, you need to assign these permissions for the IUSR_computername user account or the Everyone group. Otherwise, you need to assign these permissions to the specific Windows NT accounts that will be deploying WebClasses.       Next, you need to have a directory for deployment. If you do not already have a deployment directory, create a new directory under your C:\InetPub\wwwroot directory using Windows Explorer. This directory needs to have write permissions enabled in IIS. To do this, open the Internet Services Manager and expand the tree to show the directory to which you are deploying. This directory should be located under the Web site you are configuring for deployment. Right-click on the directory and select Properties. In the Directory tab (if your deployment directory is located in a directory directly under the wwwroot directory) or in the Virtual Directory tab (if your deployment directory is located elsewhere), enable the Write option under Access Permissions (see Figure 5). If you see a Create button on this tab, click this button, which marks the directory as an application. If you see a Remove button on this tab, your directory is already marked as an application. Using Windows Explorer, set read, write, execute, and delete (RWXD) NTFS permissions for your deployment directory.

Figure 5: Enable the Write Option

If you plan on deploying your WebClasses via the anonymous user, you will need to add an entry to your registry. To enable anonymous upload, create a new REG_DWORD value named AllowAnonymous under the HKEY_LOCAL_ MACHINE\Software\Microsoft\WebPost\Acceptors\CPSHost registry key. Set the value of this new entry to 1 (see Figure 6). For more information on anonymous uploads, see article Q179566 in the Microsoft Knowledge Base (http://support.microsoft.com/support/kb/articles/Q179/5/66.asp).       Unless you are digitally signing your CAB files, you will need to make another registry edit. To allow unsigned CAB files to be deployed to your Web server, you will need to change the ComponentRequiresSignature registry entry under the HKEY_LOCAL_ MACHINE\Software\Microsoft\Publishing\RemoteInstaller key to the value No (see Figure 6).       The final step before testing the Posting Acceptor is to update the necessary system files on your Web server (see Figure 7). Your WebClass will use these system files during runtime. Since some of these files are in use by your system, the easiest way to update them is to create a Standard Setup Package of an empty WebClass project. You will only need to do this once.       When creating your Standard Setup Package, be sure to uncheck your empty project DLL in the Include Files step of the PDW. The Standard Setup Package should only include the WebClass runtime, the Visual Basic 6.0 runtime, and the OLE Automation files. When you install the Standard Setup Package on your Web server, your system may need to reboot to update these system files because they are in use.       To test the Posting Acceptor, create an ASP page that uses a form-based file upload (see Figure 8). Replace deployment_directory in the <FORM> tag and in the default value of the second <INPUT> tag with the actual deployment directory name. After you make these modifications, save this file as upload.asp in your deployment directory.       Next, you must follow five steps to post a file to your deployment directory: Open Internet Explorer and browse to the ASP page you just created (http://machinename/deployment_ directory/upload.asp). Choose a file to upload by clicking Browse (for example, C:\temp\test.txt). Enter the location to which you are deploying (http://machinename/deployment_directory). Click Upload. Using Windows Explorer, confirm the file was uploaded successfully to your deployment directory.       If you find that this simple upload test did not work, go back through this article and double-check to make sure that you have configured your Web server properly. Also, for more information on the Posting Acceptor, see article Q192116 in the Microsoft Knowledge Base (http://support.microsoft.com/support/kb/articles/Q192/1/16.asp). Configuring the Client       Compared with the Web server, the client configuration is much simpler. All that you need installed on the client is Web Publishing Wizard version 1.53 or later (as of this writing, the most recent version is 1.6) and the PDW. You will probably find that your machine already has these two components installed. The Web Publishing Wizard installs the WebPost APIs. The PDW uses the WebPost APIs to communicate with the Web server.       To verify that the Web Publishing Wizard has already been installed, check Add/Remove Programs in the Control Panel for the Web Publishing Wizard entry. If you don't see this entry or you don't have version 1.53 or later, you will need to download the latest version from the Microsoft Web site at http://windowsupdate.microsoft.com. Once the Web Publishing Wizard has been installed, you will need to reboot your machine before you continue. Creating the Internet Package       Before you can deploy your WebClass, you need to create an Internet package using the PDW. An Internet package is a CAB file that contains your project DLL files and all associated files. The CAB file will be unpacked on the Web server and the necessary components will be installed and registered.       To create an Internet package, follow these steps: Start the PDW. Typically it is found in the Microsoft Visual Studio® 6.0 Tools folder. On the first screen of the PDW, locate your project using the Browse button, and then click the Package icon. On the Packaging Script screen, select None from the dropdown menu, then click Next. On the Package Type screen, select Internet Package and click Next. On the Package Folder screen, choose an appropriate folder and choose Next. On the Included files screen, add the appropriate files. If your WebClass is using templates, this is where you would add them to the CAB file. Uncheck the WebClass runtime mswcrun.dll and "VB6 Runtime and OLE Automation files." (These were already installed during server configuration.) Click Next. On the Finished! screen, be sure to provide a friendly name for your script, then choose Finish. The script name you provide here is the name that will be available from the Packaging Script screen. Save the report and click OK to return to the main PDW screen. The Deployment Process       At this point, you are ready to deploy your Internet package (CAB file) to your Web publishing site (your target Web server). To begin deployment, follow these steps: Click the Deploy icon on the main PDW screen (see Figure 9).

Figure 9: Deploy Icon

On the Package to Deploy screen (see Figure 10), select your package and click Next.

Figure 10: Package to Deploy

On the Deployment Method screen (see Figure 11), select Web Publishing and click Next.

Figure 11: Deployment Method

The Items to Deploy screen (see Figure 12) should contain your CAB file, any HTML templates your project requires, and an ASP page. Click Next.

Figure 12: Items to Deploy

On the Additional Items to Deploy screen click Next. A number of checks occur against the Web server. Here you can run into a few problems, especially if you have not followed the steps for configuring the server and the client discussed earlier. If you run into problems at this stage, it is better to close the PDW and restart the deployment process since information such as security credentials are cached.

Figure 13: Web Publishing Site

On the Web Publishing Site screen (see Figure 13), you have a few options to confirm. Enter the URL of the directory to which you are publishing. Make sure that HTTP Post is selected as the Web publishing protocol. Check "Unpack and install server-side cab" and click Next.

Figure 14: Saving the URL Prompt

You may see a prompt to save the URL and publishing directory in the registry (see Figure 14). Click No at this point. If your deployment is successful, then next time you may want to save the information to the registry by clicking Yes. Clicking Yes at this time will save the information under the following registry key:

HKEY_CURRENT_USER\Software\Microsoft\WebPost\Sites

If this is the first time that you are unpacking CAB files at this site, you will see a dialog warning you that the wizard has not confirmed whether the server can unpack the CAB file (see Figure 15). Click Yes to continue.

Figure 15: CAB File Dialog

Uploading Errors       At this point, you may encounter one or more of the following error messages.

"Unexpected error number 80042114 has occurred: The Web server you selected does not indicated support for the service provider you selected."

This error message can indicate a number of possible problems. The most common problem is that Posting Acceptor is missing or is installed incorrectly. Please refer to the previous section, "Installing Posting Acceptor 2.0," for suggestions. You can also check to make sure that the URL matches the post type that you have chosen. In this case, we are posting to a Web site so we need to make sure that HTTP is selected as the protocol and that the destination URL begins with http://. Also, make sure you have a default document specified and that the <META> tag is specified correctly.

"Unexpected error number 40042119 has occurred: There is no PostInfo file on the server."

This error may occur if you have typed an incorrect URL or if the URL does not refer to a correctly configured Web server. Make sure that the URL is correct and the Web server is configured properly. For proper configuration, you may need to install the Microsoft Visual Studio server-side setup on the Web server.       First, check to make sure that the Web server is running. Next, confirm that you do have a PostInfo.asp file sitting in your Web publishing site's C:\InetPub\scripts directory, and that the <META> tag in the default document has the correct path to the PostInfo.asp file. This error message could also indicate that the authenticated user does not have read permissions to the C:\InetPub\ scripts directory.

"The Web server you selected does no support cab unpacking."

There are a few things to check when you see this error. Posting Acceptor 2.0 may not be installed correctly. You may be posting to a Windows NT Workstation that does not support CAB unpacking. PDW may be retrieving cached information from the registry that has been saved from a previous deployment.

Figure 16: Deployment Report

If all went well, you will see a dialog that provides you an option to save a report containing the files deployed to the server along with their location (see Figure 16). Deployment Errors       Let's walk through the possible errors you may run into during deployment.

"Unexpected error number C0042116 has occurred: The Web server returned the following error: Files specified in section RInstallApplicationFiles of INF file mywebclass.INF are busy. Cannot install them unless allowed to do a REBOOT."

This error is addressed in Knowledge Base article Q223499 (http://support.microsoft.com/support/kb/articles/Q223/4/99.asp), and may occur if you have included files that are currently in use by the Web server, such as the Visual Basic 6.0 runtime or other system files. This error will also occur if you are trying to update your DLL without restarting the Web services of the Web publishing site. One way to stop the Web services is by entering the following command from a command prompt:

net stop iisadmin

To restart the Web services, enter net start w3svc from a command prompt:

"Unexpected error number C0042116 has occurred: The Web server either is not responding or returned an unrecognized response."

This error message usually indicates that Execute permissions have not been enabled on the scripts virtual directory.

"Unexpected error number C0042116 has occurred: The Web server returned the following error: You do not have write access to destination URL http:// <servername>/<directory>."

This error suggests one of two possibilities: you do not have Write permission enabled for the deployment directory, or the directory you specified does not exist.

"Unexpected error number C0042116 has occurred: The Web server returned the following error: Access Denied."

This error message indicates that you are only using anonymous access, and that the IUSR_computername account does not have the proper NTFS permissions. The IUSR_computername account needs read and execute (RX) permission to the C:\InetPub\scripts directory and read, write, execute, and delete (RWXD) permission to your deployment directory.

"Unexpected error number C0042116 has occurred: The Web server returned the following error: Cannot move file "<filename>" to its final destination. Further processing is stopped."

This error message indicates that the authenticated account does not have the proper NTFS permissions. The authenticated account needs read and execute (RX) permission to the C:\InetPub\scripts directory and read, write, execute, and delete (RWXD) permission to your deployment directory. It can be helpful to enable only Basic Authentication which will prompt you for credentials, so you will always know who the authenticated user is.

"Unexpected error number C0042116 has occurred: The Web server returned the following error: The signature on cabinet file XX.CAB could not be verified."

This is a friendly message straight from the Web server letting you know that you have to modify the ComponentRequiresSignature key in the registry. See Knowledge Base article Q225120 (http://support.microsoft.com/support/kb/articles/Q225/1/20.asp) for more information.

"Unexpected error C0042116 has occurred: The parameter is incorrect."

This is typically a client-side error and means that you need to install Web Publishing Wizard 1.53 or later. This error message also occurs if in deployment step 6 you get an error message and continue. Go back and address any error messages that you received in step 6.

"Unexpected error C0042116 has occurred: The Web server returned the following error: The query string "INSTALL" is invalid."

This error indicates that you do not have Posting Acceptor 2.0 installed and you are trying to unpack and install your CAB file on the server.       And don't worry. If you can get past these errors the first time you deploy a WebClass, it will get easier and easier to do in the future.

Do you have questions for FAQ? Send mail to faq@microsoft.com.

From the September 1999 issue of Microsoft Internet Developer.