Solution Building and Packaging Reference

After you've completed your development efforts, you need a way to get the fruits of those efforts to users. Where you might once have been limited to creating a setup program or using software separate from the development environment, you can now create a variety of distribution units, and all within the Microsoft development environment.

The following sections provide information to acquaint you with packaging applications in the Microsoft development environment.

Section | Description
Solution Building and Packaging Concepts | Introduces concepts key to packaging your applications with the Microsoft development environment (for Microsoft® Visual J++™ and Microsoft® Visual InterDev™).
Solution Building and Packaging Common Tasks | Provides links to step-by-step instructions for performing common building and packaging tasks.
Solution Building and Packaging User Interface Reference | Provides links to topics describing what you'll see in dialog boxes associated with building and packaging.
Solution Building and Packaging Error Messages | Provides links to topics describing error messages you may encounter when packaging your applications.


Solution Building and Packaging Concepts

With the Microsoft® development environment (for Visual J++™ and Visual InterDev™) you can create three types of packages for your projects. With this packaging, you can distribute an application on the Web or use a standard installation program. You can choose from three different kinds of packaging projects: a setup executable, a Microsoft cabinet, or a Zip Archive file. You can digitally sign your setup or cabinet projects for added security by attaching certificates in the development environment.

The following sections provide information to acquaint you with solution building and packaging in the Microsoft development environment.

Section | Description
What Is Packaging? | Provides an overview of packaging in the Microsoft development environment. Briefly describes the three types of distribution units and the two ways of creating those distribution units.
Choosing One of the Three Types of Distribution Units | Provides a brief overview of the three types of distribution units: cabinet files, setup executable files, and Zip Archive Format files.
Cabinet Packaging | Describes the Cabinet format and details on using cabinet files for packaging.
Setup Packaging | Describes the setup executable format and details on using setup files for packaging.
Zip Format Packaging | Describes the Zip Archive format and details on using Zip files for packaging in the development environment.
Two Ways to Create Distribution Units | Provides a brief overview of the two methods for creating a cabinet, setup, or Zip file: in-place with a single project or as a separate packaging project.
Distribution Unit Signing and Security | Explains digital signing, certificates, and private keys and how to get them.


What is Packaging?

Packaging bundles up your application's executable files into a single file, called a distribution unit, so that it is easier to deploy and install your application to your user's computer.

With the Microsoft development environment you can package the files required to run your application (for example Java class files, Windows .exe or .dll files, HTML pages, and so on) into easily manageable and movable distribution units. Examples of packaging are:

  • Putting all the application files for an application into a single setup (.exe) file which, when run, installs the application and adds an item to the Windows Start menu.

  • Putting all the Java .class and .gif files that implement an applet into a cabinet (.cab) file. Then, when an HTML page that references the applet is loaded, you can download and install the applet.

Create Three Types of Distribution Units

You can create three types of distribution units in the Microsoft development environment.

Distribution unit | Description
Cabinet Packaging | Contains multiple files and is compressed to download and install components from Web pages (WFC components, applets, and so on).
Setup Packaging | Contains your application files and bundles them (in compressed form) into an executable file that installs the application on the user's computer. Includes an uninstaller program.
Zip Format Packaging | Contains multiple files in a single, uncompressed Zip Archive file format supported by many Web browsers.

Two Methods of Creating Distribution Units

The Microsoft development environment helps you create these packaging types in two different ways:

  • Create in-place packaging by specifying the output format of any Visual J++ project to any of the three types (cabinet, setup, or Zip).

  • Create a distribution unit project and add it to your solution. These distribution units can be of any of the three types (cabinet, setup, or Zip).

The advantage of in-place packaging is that you can easily create a cabinet, setup, or Zip file for your single Visual J++ project. The advantage of distribution units is that you can add as many distribution unit projects to your solution as you want, and each distribution unit can collect project outputs from multiple projects.


Choosing One of the Three Types of Distribution Units

You can create three types of distribution units with the Microsoft development environment. These are:

  • Cabinet files (.cab) for the download and installation of components on Web pages. Cabinet files can contain multiple files and are compressed.

  • Self-extracting setup executable files (.exe) that package your application (in compressed form) into an executable file that installs the application on the user's computer.

  • Zip Archive Format files (.zip) for downloading applets on Web pages. Zip files package multiple files in a single, uncompressed Zip Archive file format supported by many browsers.

Packaging a Cabinet Distribution Unit

The cabinet file is an efficient way to package components on Web pages. These components, which can be multiple files, are compressed into a single cabinet file. When Microsoft® Internet Explorer opens an HTML page that references components in the cabinet file, the cabinet file is downloaded and installed on your user's computer.

Cabinet file packaging has two key features: Multiple files can be stored in a single cabinet (.cab) file; and data compression is performed across file boundaries, significantly improving the compression ratio. Additionally, .cab files generated by the Microsoft development environment contain an Open Software Distribution (.osd) file that describes the contents of the .cab file, allowing Internet Explorer to install the contents of the cabinet file.

Packaging a Setup Executable Distribution Unit

The self-extracting setup file provides a mechanism to package your application (in compressed form) into a single executable file. When run, the setup file installs the application on the user's computer.

The setup file installs the files that make up the applications on the user's computer, and creates a Windows Start menu item so that your user can start the application. The setup file also installs an uninstalling program so that the user can remove the application using the Windows Control Panel Add/Remove Programs dialog box.

Packaging a Zip Archive Format Distribution Unit

The .zip file provides a mechanism to package applets on a Web page so that they can be downloaded and run by Internet Explorer and many other Web browsers. In the Microsoft development environment, Zip Archive files package multiple files into a single, uncompressed Zip Archive file. When the Web browser opens an HTML page that references applets in the Zip Archive, the Zip Archive file is downloaded to the user's computer.


Understanding Cabinet Files and .osd Files

Cabinet Packaging

The cabinet file is an efficient way to package components on Web pages. You can use cabinet files to deploy Java classes for use through Internet Explorer 3.0 and 4.0. Cabinet files also support installation of Java classes in the Java Package Manager when used with Internet Explorer 4.0.

When packaging with cabinet files, you should understand:

  • Internet Explorer code download and the Java Package Manager.

  • Cabinet files and Internet Browsers.

  • Setting Java permissions and security levels for cabinet files.

  • What happens when deploying a cabinet file.

  • Cabinet file compression.

For More Information For more information on digital signing, see Distribution Unit Signing and Security.

Internet Explorer Code Download and the Java Package Manager

The Java language supports the concept of Java packages to manage the namespace of classes, but does not provide for installing or managing packages. The Microsoft® Win32® Virtual Machine for Java (Microsoft VM) provides package management services with the Java Package Manager (JPM). Microsoft Internet Explorer 4.0 uses the Java Package Manager to provide code download services for Java applets. You can exploit these code download services by using the Microsoft development environment to package your Java classes into a cabinet file.

In order to use Internet Explorer 4.0 and Java Package Manager code download services, all the Java classes in the cabinet file must be in a Java Package. A Java Package is a collection of classes that share a common namespace. For instance, if a class named "test.java" contains the line "package com.ms.fx", the full name of the compiled class would be "com.ms.fx.test". For further information about how to create Java packages, see the Visual J++ documentation.

Cabinet Files and Internet Browsers

Cabinet files can contain an inventory file called an .osd file. The Microsoft development environment automatically creates the .osd file. This file contains a list of all the Java packages and applications in the cabinet file. The .osd file instructs Internet Explorer 4.0 to install the contents of the cabinet in the Java Package Manager. The .osd file also contains a friendly name that is displayed in the Windows Downloaded Program Files folder when the cabinet file is installed.

Setting Java Permissions and Security Levels for Cabinet Files

Cabinet files can carry additional security information in the digital signature to specify Java permissions. When signing cabinet files that contain Java components, you can specify the permissions that the Java component requires, allowing the components to access more features of the local system. This brings applets equal to the capabilities of Microsoft® ActiveX® controls without sacrificing the security in the Java implementation.

Signing a cabinet file with Java permissions gives developers more detailed control over the security restrictions placed on their Java component. Java permissions are optional.

Setting Java permissions also cuts down on the number of dialog boxes presented to your user. Java classes may automatically receive some permissions when Microsoft Internet Explorer zones are used.

Note If you are using only ActiveX controls in your cabinet file, do not use the Java permissions for signing security levels.

Cabinet files may contain both Microsoft ActiveX Controls and Java code. Because ActiveX controls must be fully trusted to run, they are treated differently from Java code. For ActiveX controls to run when they are in a cabinet file that uses Java permission signing, you must specify that the cabinet file may contain ActiveX controls in the signature. Then, when you include ActiveX controls in the cabinet file, they will either be denied, allowed to run, or query the user, depending on the security settings of the zone.

Permission Levels

With the Microsoft development environment, you can easily sign a cabinet file at four possible security levels: high, medium, low, and custom.

High security level means lots of restriction for your Java applet or application. This level ensures that the Java code contained in the cabinet file will only run in the Java "sandbox" (a protected space that prevents the applet from accessing files and selected system services). Signing a cabinet file with the high security setting ensures that the Java code will never be able to do more than it would in the sandbox, regardless of where the code came from or what the user allows it to do. Because the Java code is so restricted, the applet or application will be allowed to run without any intervention from your user.

Medium security level means high security with some exceptions for your Java applet or application. Applets signed with the medium security level request user-directed I/O, store data (up to 1MB) in the user's computer scratch space (storage on the client machine that an applet can safely access without needing full access to the client file system), and call user-directed file I/O routines, to ensure that all file operations are done with your user's intervention. A cabinet file signed with medium security will run without intervention in Low and Medium security zones. Zones are areas of control as defined by Microsoft Internet Explorer.

Low security level means there are no restrictions on the Java code in the cabinet. Only a zone set at Low security can grant this much access without first asking the user. High and medium security prompt the user before running the applet.

With the custom level, you can set the specific, individual permissions that the Java classes need.

You can reach these settings in the development environment by right-clicking on your cabinet packaging project and pointing to Properties. These options are listed in the Java Permission tab of the Cabinet Properties dialog box.

For More Information For more information, see "Trust-Based Security for Java" in the Microsoft SDK for Java.

What Happens When Deploying a Cabinet File

When Java classes are packaged into cabinet files and .zip files, the HTML tags that reference the classes in the cabinet files and .zip files must also reference the deployed cabinet files and .zip files. The Microsoft development environment deployment feature performs all required modifications to the HTML to ensure that all <APPLET> and <OBJECT> tag references to Java classes deployed in cabinet files and .zip files are properly maintained.

Cabinet File Compression

As components on Web pages become larger and more complex, it is increasingly important to find a fast and effective way to download the required classes. By default, Java classes are downloaded one .class file at a time and in uncompressed format. In this case, not only is additional time needed to negotiate the transfer of each file, but extra bytes may be transferred because of the lack of compression. For feature and class-rich Java authored components, this download time can be excessive.

A cabinet file can serve as a single, compressed repository for all .class files and all audio and image data required by the Java applet. Only the cabinet file is downloaded, so the time of download is whatever it takes to negotiate the transfer and download the compressed bytes. Once downloaded, the system extracts and installs the contents of the cabinet file.


Overview of Self-Extracting Setup.exe Files

Setup Packaging

A setup executable distribution unit is a package that builds a setup (.exe) file. This file can be transferred to the user's computer, installed, and run there.

When packaging with setup files, you should understand:

  • Why to use a setup distribution unit.

  • Creating setup files.

  • Installing core components with setup files.

  • Installing components authored in Microsoft® Visual Basic®.

  • Using Setups to Install COM Components.

  • Using Web pages to distribute a setup file.

Why Use a Setup Distribution Unit?

Setup executable files you create with the Microsoft development environment provide a professional way to distribute your application.

A simple way to distribute your application is to create a setup program that, when run, will install your application on the user's computer. This is best used for conventional Windows applications — Web-based applications are better distributed as cabinet files, which the Microsoft development environment can also create for you.

The Microsoft development environment provides a setup distribution unit that creates the setup file for you. It creates a single executable that contains all the files that need to be installed, so it can be distributed on conventional media like floppy disks or CDs, over a network, or even from a Web page.

The files are stored in a compressed format in the setup file, so they take up as little disk space as possible, and reduce Web download times. The files are automatically uncompressed during the installation process.

The setup file also registers an uninstaller, so your application will be listed in the Add/Remove Programs dialog box in the Windows Control Panel, and can be uninstalled from this dialog box.

The setup file can be digitally signed so that users downloading the file from a Web page can be sure that you published the application and that it was not tampered with in any way.

Creating Setup Files

With the Microsoft development environment, you can create and customize setup files more easily than before.

  • You can package the outputs of a Visual J++ project. If the outputs of the project change, the setup file will be automatically rebuilt.

  • The setup file created is a professional, Windows logo-compliant installer, with a professional user interface and an uninstaller.

  • Any ActiveX components included in the package are automatically registered on the target machine.

For More Information For step-by-step instructions, see Creating a Setup File.


Installing Core Components with Setup Files

Some of the files that a setup file must install are "core" files, which must be treated in special ways in a Windows logo-compliant installer. Core files are usually placed in a default location so that other applications can use the same files.

While core files can be installed, they must never be removed during an uninstall process. The Microsoft development environment knows which files are core files, and creates a Windows logo-compliant installer in the setup distribution unit without your needing to know whether a particular file is a core file or not — just add whatever files are needed and the development environment will treat them correctly.

In this topic you can:

  • Learn more about handling core components in a setup distribution unit.

  • Check and update the core component list.

Handling Core Components in a Setup File

Core components are all files included with the operating system, plus crucial files that may be added by secondary installations, such as ODBC, DirectX, and similar components. These core components are shared by many applications and should be installed in the same common folder (which is almost always the Windows System folder) by each application's installer or setup program.

The Microsoft development environment contains a list of core components and will automatically create a setup file that handles core components correctly (they will not be removed during uninstallation, for example).

Although the development environment knows which files are core files, you must specify that a core file should be installed in the Windows System folder, because the development environment will not do this by default.

An important Microsoft logo requirement for setup distribution units is that applications must not register, reference count, uninstall, or overwrite any core components of the operating system (although they may check versions and upgrade.).

For More Information For step-by-step instructions on installing shared files in the system folder, see Installing Shared Files in the System folder.

Checking and Updating the Core Component List

New files are sometimes added to the core component list. The core component list that was included with the development environment was current at that time, but changes may have been made since then. Veritest, Inc., maintains a list of core components at their Web site. You can download the list of core components from this site and use it to update the list the development environment uses. To do this, download the Corelist.exe file and run it to extract the Corelist.txt file, and then use it to replace the file Corelist.txt in the Microsoft Visual Studio\Common\Ide\Ide98 folder.

It is good practice to check the core file list before the final build of a setup file that you will be distributing to your users. The core file list is relatively stable and doesn't change that often, so it isn't necessary to check the list before every build.


Installing Components Authored in Visual Basic

You can include components written in Visual Basic in a setup project by including the Visual Basic components and all the files that they depend on in the setup project. However, it is often easier to use Visual Basic's Package and Deployment Wizard to build a setup. You can then include these Visual Basic-authored setup files as a nested setup in a Microsoft developer environment setup project.

Such internal, nested setups are automatically run first, when your users run the outer setup (.exe) file that the setup project generated.

If the component authored in Visual Basic is a COM component (such as an ActiveX control), then like all COM components, it is best to install them in the Windows System folder (in the Visual Basic-authored setup).

Even if you don't want to use a nested setup, running the Package and Deployment Wizard on the Visual Basic project for the component is a quick and easy way to determine the correct set of files that need to be included in your self-installing setup file with the component.


Using Setups to Install COM Components

COM components such as ActiveX controls must be registered when they are installed to allow applications to use them. The Microsoft development environment will do this automatically for any ActiveX components you include in your setup distribution unit. When the component is uninstalled with the setup distribution unit, the setup removes the component from the registry.

Windows keeps track of the number of setup programs that have installed the same component. The component is only removed when all the applications using it are uninstalled. The counting of these applications per shared COM component is based on the absolute path of the file. It is important for such components to be installed in the same folder by all applications that include them.

The Microsoft development environment provides a means of installing such COM components in the Windows System folder through a setup distribution unit so they can be shared between applications. For step-by-step instructions, see Installing Shared Files in the System Folder.

The count of the applications using the component is based solely on the location of the file (the absolute path of the file) and not the CLSID (class ID) of the component. It is good practice to change the name of the file if the CLSID of the component ever changes, or it is possible to leave entries for the old CLSID in the registry that point at a file that can no longer create that component.

For DCOM components, the Microsoft development environment setup distribution unit provides a means to install references to remote DCOM servers by including the .vbr and .tlb files (created by Visual Basic and Visual J++ when they build remote servers). You would want to do this if your application used a central server — for example a bank account server that provided access to a user's bank account details. Centralizing the access to sensitive information like this behind a server provides a more secure system, because the only access to the data is through the server.


Using Web Pages to Distribute a Setup File

A Web page is a good way to easily distribute your setup distribution unit to a large group of people. Rather than giving them floppy disks or telling them to run the setup from a network address, you can simply point them to a Web page that tells them what the application does and provides a link that will install it on their machine.

The following is a typical piece of HTML that creates a link to a setup program.

<a href="BankAccount Setup.exe">Click here to install the Bank Account Access Application.</a>

In most browsers, clicking on this link will display a dialog box asking if the file should be downloaded to the user's machine or run from its current location. To avoid confusion, you should usually include instructions on your Web page to tell your users to select the "Run from current location" option.

Unless you digitally sign your setup distribution unit, most modern browsers will warn the user that the program they are about to run is not from a trusted source. Signing your application is a simple operation. Signing helps your users be sure that the application they are installing is from you and hasn't been tampered with. The Microsoft development environment provides the ability for you to sign your setup file.

For More Information For more information on information introduced in this topic, see:

  • Creating a Setup

  • Distribution Unit Signing and Security

  • Signing a Setup


Zip Format Packaging

The .zip file provides a mechanism to package multiple files in a single, uncompressed Zip Archive file. You can create Zip packaging projects in the Microsoft development environment. These Zip packaging projects generate an uncompressed Zip Archive Format distribution unit in a file packaging standard supported by Internet Explorer and other browsers.

For example, .zip files can bundle together Java class files into an archive that can be read by any browser.


In-Place Packaging Compared to Standalone Distribution Units

Two Ways to Create Distribution Units

You can use two different methods for generating a distribution unit. These two methods apply to all three types of distribution units (setup, cabinet, and .zip).

You can create distribution units two different ways in the Microsoft development environment. You can:

  • Create an in-place packaging configuration of any of the three types for a single Visual J++ project.

  • Create a distribution unit project of any of the three types in the solution.

The first method is to use the "in-place" packaging configuration of a Visual J++ project. You can specify in the property pages of the Visual J++ project that when the project is built, the outputs of the project should be placed in a setup, cabinet, or .zip file. You can only add one in-place packaging configuration to each Visual J++ project.

The second method is to create a distribution unit project. A distribution unit project can contain the outputs of many projects. You can add as many distribution unit projects to your overall project or solution as you like. You can add different types of distribution unit projects to your solution, as well.

Tip To see the properties for a distribution unit project, right-click the project and point to Properties. To see the properties of an in-place packaging configuration of a Visual J++ project, right-click the Visual J++ project, and point to Properties. On the Properties dialog box, choose the Output Format tab and click Advanced.

Understanding Project Outputs

With the Microsoft development environment, you use "outputs" of a project to control the files placed in a distribution unit or to control the deployed files. The "outputs" of a project are the set of files that are required at run time to run the project. For example, the outputs of a Visual J++ applet project would be the HTML pages and Java class files. The outputs of a Visual J++ project can be set by the user on the Project Properties Deployment Property tab, where the user can specify either the file types (for example, *.class) or file names. So, if you are creating a cabinet file by adding one or more Visual J++ projects to a cabinet project, you can control which specific files end up in the cabinet project by modifying the file types or names on the Deployment Property tab for that Visual J++ project.

Creating In-Place Packaging Configuration for a Visual J++ Project

The in-place packaging configuration provides a simple method to quickly package the components you are building in a Visual J++ project. You can specify that when the project is built, the outputs of the project should be placed in a cabinet, Zip Archive, or setup distribution unit. You can specify this on the Visual J++ project's property pages. You cannot create more than one in-place distribution unit per project, however.

Specifically, to create an in-place packaging configuration, you simply select the project's properties, and on the Output Format property tab, specify the following.

  • The type of distribution unit (cabinet, setup, Zip, Windows .exe file, or Windows .dll file).

  • The project output files that should be put into the distribution unit. You can specify the file types by extension (for example, *.class) or specify the names of the specific files to be included.

  • Any additional files that are not part of your project.

You can also set the properties specific to the type of distribution unit you choose. You can reach the appropriate property pages by going to the Output Format page, and then clicking Advanced.

Once these properties are set, a distribution unit will be built each time the project is built. The distribution unit is also available as a deployable output of the project.

Creating Distribution Unit Packaging Projects

With the Microsoft development environment, you can package many projects into a single distribution unit, such as a cabinet, Zip, or setup executable. This way, you can distribute the outputs of several projects with a single file.

Distribution unit projects are development environment projects whose only purpose is to generate .cab, .zip, or setup (.exe) files. There are three types of packaging projects: cabinet, setup executable, and Zip Archive projects. These projects can be added to a solution (by selecting Add Project and in the Add Project dialog box, selecting Visual Studio, and then clicking the Distribution Units node).

Distribution unit projects can contain the following two kinds of information.

  • References to the project outputs of other projects.

  • Files that are included in the distribution unit when it is built.

Referencing Other Project Outputs in a Packaging Project

The project outputs contain references indicating:

  • When the distribution unit is built.

  • The referenced project built.

  • The outputs from the referenced project included in the distribution unit.

For example, when you build "MyCabinetProject," any projects will be built, and the outputs of both projects will be put into a cabinet file generated by "MyCabinetProject."

Including Additional Files in a Distribution Unit

You can also add files to a distribution unit that are included when you build the distribution unit. These files may or may not require building on their own.

For example, when you build "MyCabinetProject," a file such as "flowers.bmp" and "readme.txt" will be put into the cabinet file generated by "MyCabinetProject."


Distribution Unit Signing and Security

With the Microsoft development environment, you can sign your cabinet and setup files with a digital identification. You can use digital signing to help your users trust the contents of your distribution units, by ensuring the distribution unit is authentic and has not been tampered with.

When signing distribution units, you should understand:

  • Digital signatures in the development environment.

  • Acquiring a certificate.

  • How a digital signature works.

  • Keeping your private key secure.

Digital Signatures in the Development Environment

You can sign distribution units in the development environment with two kinds of signature certificates.

  • The Visual Studio test certificate

  • An individual or corporate certificate

The Visual Studio test certificate is provided for you to test the behavior of a signed distribution unit, but should not be used to sign components that you want to distribute. The text on the Visual Studio test certificate indicates that components signed with it should not be trusted.

A certificate authority to identify an individual or corporation issues an individual or corporate certificate. It is made up of two components: the certificate file and a private key. Both are required to sign a distribution unit. Additionally, you can specify the URL of a timestamp server that will record on the distribution unit the date that it was signed. Any distribution units you provide for commercial purposes or to other people should have your own certificate file attached (rather than the test certificate).

A certificate is a set of data that identifies the original creator of the file, and the time and date of the file's creation (timestamp) as registered with a certificate authority. The data set in a certificate includes your public key. When you sign a file with your private key, the recipient of the file can use the public key (retrieved from the certificate you sent or from the certificate authority) to verify your identity.

To check or change the signing settings for your distribution unit, see the property pages for the Visual J++ or distribution unit project. For cabinet projects, see the cabinet's main property tab of the property page dialog box. For setup projects, see the Signing tab of the property page dialog box.

The default signature settings for the development environment are set in the Security Page, located on the Options dialog box, under the Tools menu. These settings include whether files are signed at all, signed with the test certificate, or signed with the custom certificate you provide, and are the default values for signing cabinet projects and setup projects. The settings are copied automatically from this Options page to the project's property page for signing; you can then modify them to suit the needs of the particular project you created.

Acquiring a Certificate

To get a certificate, you need to provide information about yourself to a certificate authority, for example, Verisign, Inc. If you are applying as a representative of your corporation, you need to give the certificate authority all your personal information, pledge that your software will cause no harm to another's computer or software, and provide the Dun & Bradstreet Rating for your corporation. If you are applying for individual certification, you need to provide your personal identification and pledge that your software does not knowingly contain any harmful elements to another computer or another's code.

Understanding How a Digital Signature Works

Digital signing attaches an identity to a distribution unit that says where the code came from.

Signing a distribution unit with a digital signature does not alter the contents of the distribution unit; the digital signature is bundled with the data. There are two parts to a digital signature; the public key and the private key. These are two parts of an algorithm. The public key is available to everyone. The private key is available only to the owner of that digital signature.

When attaching a key to a file, the private key encrypts a special cryptographic digest of the file, signing the file when the file and the signature are sent, the recipient browser produces another special cryptographic digest of the file with the public key. Then the public key digest version of the file is matched against the recipient's private key digest version of the file. If those two match, the file is safe and was not tampered with.

The receiving browser decrypts the signed file with the public key.

Keeping Your Private Key Secure

Once you receive your own digital signing certificates, keep your private key as secure as possible. If another person got a hold of your private key, they have the potential to distribute information on the Internet or intranet in your name. Specifically, do not place your private key on removable media, on shared drives, or send it in e-mail.


Solution Building and Packaging Common Tasks

This section contains step-by-step instructions for the most common Microsoft development environment tasks for building and packaging solutions and projects.

These tasks include:

Adding Nested Setups Into a Setup Distribution Unit

Adding or Removing a Project from a Distribution Unit

Adding or Removing Additional Files from Distribution Units

Adding or Removing Files from the In-Place Packaging Configuration of a Visual J++ Project

Building a Solution or Project

Configuring a Setup to Contain References to Remote DCOM Servers

Creating a Cabinet (.cab) File

Creating a Self-Extracting Setup Executable File

Creating a Zip Archive (.zip) File

Creating Start Menu Items for Setup Distribution Units

Displaying the Deployment Tab

Displaying the Output Format Tab

Displaying the Property Pages of a Distribution Unit

Installing Shared Files in the System Folder

Setting Java Permissions for a Cabinet (.cab) Distribution Unit

Setting the Active Build Configuration

Setting the Outputs of a Visual J++ Project

Signing a Cabinet (.cab) Distribution Unit

Signing a Self-Extracting Setup Distribution Unit

Specifying External Dependencies for a Cabinet (.cab) Distribution Unit

Specifying a Cabinet's Name, Friendly Name, and Version Number


Adding Nested Setup Files Into a Setup Distribution Unit

When you are working with applications made up of several components (such as Microsoft® ActiveX® controls), you can:

  • Create separate setup distribution units for each component.

  • Create separate setup distribution units to install each component and then nest these setup distribution units together.

When a nested setup is deployed or downloaded on the target computer, the innermost setup distribution unit runs first, and then the overall setup distribution unit. This strategy is appropriate when the components are used by several applications, or when the components are provided by a third party as a setup distribution unit, and you are not sure what is involved with that installation.

To add a nested setup to a setup distribution unit

  1. In the Project Explorer, select the setup distribution unit in which you want to place the nested setup file.

  2. On the Project menu, click Add Item.

  3. In the Add Item dialog box, click Browse and find the setup (.exe) file. Select this file and click Open.

  4. In the Project Properties dialog box, click the Nested Setups tab.

  5. Select the check box next to the nested setup file that you have just added to the project.

  6. Click OK.

Generate the setup files and add them to the project containing the in-place setup distribution unit. You can add files to the project by right-clicking the project, selecting Property Pages, and then clicking the Output Format tab. Click Include Additional Files.

To add a nested setup file to a setup in-place packaging configuration in a Visual J++ project

  1. In the Project Explorer, select the project containing the in-place setup, right-click, and then click Properties.

  2. In the Project Properties dialog box, click the Output Format tab.

  3. In the Output Format tab, confirm that the Enable Packaging check box is selected and the Self-extracting Setup (.EXE) option is chosen for the packaging type.

  4. Click Include Additional Files.

  5. In the Add Additional Files dialog box, click Add.

  6. In the Browse for Package Output File dialog box, find the setup (.exe) file. Select this file and click Open.

  7. In the Add Additional Files dialog box, click OK.

  8. Click Advanced to get to the property pages for that setup distribution unit.

  9. Click the Nested Setups tab.

  10. Select the check box next to the setup file that you have just added to the project.

  11. Click OK.


Adding or Removing a Project From a Distribution Unit

You can add and remove items and projects from packaging projects in the Project Explorer.

To add a project to a distribution unit project

  1. In the Project Explorer, choose the distribution unit project to which you want to add a project.

  2. On the Project menu, click Add Project Outputs.

  3. In the Add Project Outputs dialog box, choose the project and item that you want to add to the distribution unit.

  4. Click Open.

    When you build the project, the outputs of the added project will be included.

To remove a project from a distribution unit project

  1. In the Project Explorer, choose the project or item in the distribution unit project that you want to remove.

  2. On the Edit menu, click Remove.


Adding or Removing Additional Files from Distribution Units

You can add files to a distribution unit project to be included in the distribution unit after the project is built.

To add additional files to a distribution unit project

  1. In the Project Explorer, select the distribution unit in which you want to place the added items.

  2. On the Project menu, click Add Item.

  3. Browse around and find the items you want to add. Select the items and click Open.

To remove additional files from a distribution unit project

  1. In the Project Explorer, select the file in the distribution unit project.

  2. On the Edit menu, click Remove.


Adding or Removing Files from the In-Place Packaging Configuration of a Visual J++ Project

You can generate distribution units two ways with the Microsoft development environment. You can configure a Microsoft® Visual J++™ project to generate a distribution unit by setting the packaging attributes on the property pages for the Visual J++ project. You can control the files placed in the distribution unit, as well.

To add additional files to the in-place packaging configuration of the Visual J++ project

  1. Display the output format tab for the Visual J++ project.

  2. Click Include Additional Files.

  3. In the Add Additional Files dialog box, click Add to place additional files on the list. Choose any files. Click Delete to remove any files from the list.

  4. When you are done arranging the list of added files, click OK.

    The files in the list will be included in the distribution unit when the Visual J++ project is built.

To remove additional files from the in-place packaging configuration of the Visual J++ project

  1. Display the output format tab for the Visual J++ project.

  2. Click Include Additional Files.

  3. In the Add Additional Files dialog box, select any files that you want to remove from the list. Click Delete to remove the files.

  4. When you are done arranging the list of added files, click OK.

    The files included with the distribution unit will be updated when the Visual J++ project is built.


Building a Solution or Project

When you build your solution or project, you are building the active (default) build configuration. The two possible build configurations are: Debug or Release.

You can control the order in which files are built in the Build Order dialog box. For more information, see the Visual J++ documentation.

To build a solution

  • On the Build menu, click Build Solution.

To build a project or specific package

  1. In the Project Explorer, select the project or distribution unit.

  2. On the Build menu, click Build <project>.


Configuring a Setup to Contain References to Remote DCOM Servers

You can include references to remote DCOM servers in your setup project. In distributed applications, the controlling client application resides on one computer, but the data is on another computer. The client application accesses the remote data through a remote DCOM server. You must first register the remote DCOM server on the client machine before it can be used.

There must be certain DCOM files available before you can configure the setup executable to reference a remote DCOM server. These files are usually labeled .tlb and .vbr, and can be created by both Microsoft® Visual J++™ and Microsoft® Visual Basic® when they build a project. Adding both of these files to the self-extracting setup executable project will enable the referencing ability of the setup project.

To add remote DCOM server files to a Visual J++ Project

  1. Display the output format tab.

  2. In the Output Format dialog box, in the Packaging Type drop-down list, choose Self-extracting Setup (.EXE).

  3. Click Include Additional Files.

  4. In the Add Additional Files dialog box, click Add. Find the .tlb and .vbr files and add both to the list in the Add Additional Files dialog box. Click OK.

    Next you can add the remote file references to your setup project.

To add remote server file references to a setup distribution unit

  1. Display the property pages of the distribution unit.

  2. Click the Remote Components tab.

  3. In the Remote Components tab, enter the name of the default remote server that you want to run the remote component. This is optional.

  4. Select the Always prompt user for server check box if you would like to ask the user for their remote server.

  5. Select the check box next to the remote components in the list. Each name in the list matches to both files (the .tlb and .vbr files) needed to reference that component. Only files you have added to the project appear here.

  6. Click OK.


Creating a Cabinet (.cab) File

There are two ways to create a cabinet file. You can create an in-place packaging configuration as a part of a Visual J++ project, or you can create a distribution unit project.

To create a .cab file as an in-place packaging configuration of a Visual J++ project

  1. Display the output format tab.

  2. Select Enable Packaging. From the Packaging type drop-down list, choose the Cab archive (.cab) packaging type.

  3. Pick the contents that you want in the cabinet file. See Setting the Outputs of a Visual J++ Project.

  4. Click Advanced and adjust any settings for Cabinet (CAB) Properties, Java Permissions, or External Dependencies. Click OK or Apply.

  5. In the Visual J++ project properties dialog box, click OK or Apply.

To create a .cab file using a cabinet distribution unit project

  1. On the File menu, click New Project.

  2. Expand the Visual Studio node. Choose Distribution Units.

  3. Choose the Cabinet (CAB) packaging type.

  4. Make any adjustments to the name and location, if needed. Select Close current solution or Add to current solution, as needed.

  5. Click Open.

  6. Add any files or projects to the distribution unit. See Adding or Removing Additional Files from Distribution Units and Adding or Removing Projects from Distribution Units.


Creating a Self-Extracting Setup Executable File

There are two ways to create a distribution unit like a self-extracting setup executable file. You can create an in-place distribution unit as a part of a language-based project, like Visual J++, or you can create a packaging project.

Building the project before packaging is recommended if you are going to select specific .class files to install. If necessary, it also starts the browser and loads an HTML page included in the project.

To create a self-extracting setup executable file as a standalone packaging project

  1. On the File menu, click New Project.

  2. Expand the Visual Studio node. Click Distribution Units.

  3. Click Self-Extracting Setup.

  4. Make any adjustments to the name and location, if needed. Select Close current solution or Add to current solution, as needed.

  5. Click Open.

To create an in-place setup package

  1. In the Project Explorer, select the project, then right-click Project Settings.

  2. In the Project Settings dialog box, click Output Format. Click Enable Packaging, and then from the Packaging Type drop-down control, select Self-Extracting Setup (.EXE).

  3. Click Advanced.

  4. In the Advanced Settings dialog box, you can do any of the following, as needed:
    • Specify the title of the application your setup distribution unit will install on the client machine. This title will appear in the user's Add/Remove Programs dialog box, available from the Windows Control Panel.

    • Set the default installation directory, either as an absolute directory path name or as a path name relative to the Program Files directory.

    • Specify that your setup distribution unit should create a Start menu item from which the user can run your application.
  5. Click Build to build the project. When this is completed, confirm that your setup distribution unit was built in the correct location.

  6. Test the packaged setup file by running it.

    When testing, confirm that your distribution unit installs all of the files you included in it, such as Java .class files, HTML pages, readme files, .gif files, or others.

    Check also to see that your setup distribution unit added your application's name to the Add/Remove Programs dialog box, available from the Windows Control Panel. Once you have finished confirming the success of your installation, you should also launch the uninstaller from the Add/Remove Programs dialog box to check that it correctly removes your application.

You should now have a self-extracting setup distribution unit containing the files you specified, and an uninstaller.


Creating a Zip Archive (.zip) File

There are two ways to create a Zip Archive format file in the Microsoft development environment. You can create an in-place packaging configuration as a part of a Visual J++ project, or you can create a distribution unit project.

To create a .zip file as an in-place packaging configuration of a Visual J++ project

  1. Display the output format tab.

  2. In the Output Format dialog box, select Enable Packaging. From the Packaging type drop-down list, choose the Zip Archive (.ZIP) packaging type.

  3. Pick the contents that you want in the cabinet file. See Setting the Outputs of a Visual J++ Project.

  4. In the Visual J++ project properties dialog box, click OK or Apply.

To create a .zip file using a distribution unit project

  1. On the File menu, click New Project.

  2. Expand the Visual Studio node. Click Distribution Units.

  3. Click ZIP File.

  4. Make any adjustments to the name and location, if needed. Select Close current solution or Add to current solution, as needed.

  5. Click Open.

  6. Add any files or projects to the distribution unit. See Adding or Removing Additional Files from Distribution Units and Adding or Removing Projects from Distribution Units.


Creating Start Menu Items For Setup Distribution Units

You can create an entry in the Windows Start menu for the application your setup project installs. These entries can only be in the Programs menu of the Start menu, and only at the top level. When your setup project self-extracts on the target computer, a new item is added to the Windows Start menu for the application.

To create a start menu item for a setup executable distribution unit

  1. Display the property pages of the distribution unit.

  2. Click the Target tab.

  3. In the Target dialog box, select the Create an entry in the Start menu check box.

  4. Enter or edit the appropriate Start menu shortcut name.

  5. Enter the command line program that is activated from the Start menu item. You can also enter any command line arguments for this program. The following variables can be entered by hand, or click Insert Default:
    • <AppDir> — The folder to which the application is installed.

    • <IeDir> — The folder in which Microsoft® Internet Explorer is installed.

    • <WinDir> — The Windows folder.

    • <SysDir> — The Windows System folder.
  6. Click OK.


Displaying the Deployment Tab

You can use the Deployment tab of the Visual J++ project properties dialog box to control which files are propagated when the project is either deployed, or added to a distribution unit project.

To display the Deployment tab of a Visual J++ project

  1. In the Project Explorer, select the Visual J++ project.

  2. On the Project menu, click Properties.

  3. Click the Deployment tab.


Displaying the Output Format Tab

The Output Format tab is a property page of a Visual J++ project. You can use this tab to configure packaging options that create a cabinet, setup, or Zip Archive format file.

To display the Output Format tab

  1. In the Project Explorer, select the Visual J++ project.

  2. On the Project menu, click Properties.

  3. Click the Output Format tab.


Displaying the Property Pages of a Distribution Unit

You can display the property pages of a distribution unit two ways, depending on whether you created the distribution unit as a Microsoft® Visual Studio™ distribution unit project or an in-place packaging configuration of a Microsoft® Visual J++™ project.

You can see a distribution unit projects in the Project Explorer.

Displaying the property pages of a distribution unit project

  1. In the Project Explorer, choose the distribution unit project.

  2. On the Project menu, click Properties. The property pages for the selected distribution unit project appear.

In-place packaging configurations for Visual J++ projects are created when you choose Enable Packaging from the Output Format tab of the selected Visual J++ project. Because you cannot see them from the Project Explorer, you select the Visual J++ project in the Project Explorer.

Displaying the property pages of an in-place packaging configuration in a Visual J++ project

  1. In the Project Explorer, choose the Visual J++ project.

  2. Click the Output Format tab.

  3. In the Output Format dialog box, select Enable Packaging.

  4. In the Packaging Type drop-down list, choose the appropriate distribution unit: Self-extracting Setup (.EXE), Cabinet (CAB), or ZIP Archive Format (.ZIP).

  5. Click Advanced to display the property pages for the appropriate distribution unit.


Installing Shared Files in the System Folder

Sometimes programs share the same files or components. If all the shared components are stored in the same place, uninstalling one application won't uninstall a file needed by another application.

With the setup distribution unit, you can specify that shared files be installed to the Windows System folder.

If your project contains Visual J++ elements, build the project first, so that all project outputs are identified. Adding additional files will increase the file list in the System Directory Installation tab of the Setup Project Properties dialog box.

To install a shared file into the Windows System folder when the setup file extracts

  1. Display the property pages of a distribution unit.

  2. Click the System Directory Installation tab.

  3. In the System Directory Installation (Setup Project Properties) dialog box, select the files in the list that you want to install to the Windows System folder of the target machine (after the setup executable extracts).


Setting Java Permissions for a Cabinet (.cab) Distribution Unit

With the Microsoft development environment, you can sign cabinet files with Java permissions. You can specify certain permissions within the system to restrict the cabinet file.

To set Java permissions for a cabinet distribution unit

  1. Display the property pages of a distribution unit.

  2. Click the Java Permissions tab.

  3. In the Java Permissions dialog box, select the Sign Cabinet with Java Permissions check box.

  4. Choose your permission level. You can pick Low, Medium, High, or Custom. If you choose Custom, you can select the individual permissions from the Permissions list.

  5. If the cabinet (.cab) distribution unit contains Java components and ActiveX controls, select the Contains ActiveX controls check box. If your cabinet file contains only ActiveX controls, do not use Java permissions.

  6. Click Apply or OK.


Setting the Active Build Configuration

There are three ways to set active build configuration for your solution. You can change it from the Build menu and Solution Properties Grid.

To change the settings for a particular configuration and project

  1. In the Project Explorer, select a project.

  2. On the Project menu, click Properties.

  3. From the Configuration drop-down control, choose Debug, Release, or All Configurations.

To change the build configuration on the menu

  1. On the Build menu, click Build Configuration.

  2. From the drop-down list, choose Debug or Release.

To set the active build configuration on the Solution Properties Grid

  1. Select the solution.

  2. On the Solution Properties Grid, the configuration entry appears, named ActiveCfg, with Debug or Release as a value.

  3. Click the drop-down list arrow to the right of the value to change it.


Setting the Outputs of a Visual J++ Project

When a Visual J++ project is deployed or included in a distribution unit project, the outputs of the project are deployed or packaged. In this context, the outputs are the set of files required at run time to run the component or application built in the project. You can specify the files that make up the outputs of your project.

To add and remove files to/from the list of outputs for your Visual J++ project

  1. Display the Deployment tab for the project.

  2. You can set the outputs of the project in two ways: You can set the file types (sorted by file extensions) or you can select specific files.
    • To set the outputs by file type, click Outputs of type. Select the appropriate filter. You can customize the filter by editing the filter string.

    • To set the outputs by selecting specific files, click These project outputs. The list box shows a list of all the available files in the Visual J++ project, and you can choose the files you want to include in the packaging configuration.

    A distribution unit generated by specifying the packaging configuration of a Visual J++ project is always included in the Visual J++ project's output files, regardless of the filter or files selected.

  3. Click OK or Apply.


Signing a Cabinet (.cab) Distribution Unit

A cabinet file can be signed. The Microsoft development environment provides a convenient means to apply a digital signature to a cabinet distribution unit.

To sign an in-place cabinet (.cab)

  1. Display the property pages of a distribution unit.

  2. In the Cabinet Properties tab, select the Sign Cabinet check box.

  3. If you have a personal certificate and private key (for example, from Verisign, Inc.), click Use Certificate file, and then specify the certificate, the private key file name, and the timestamp server URL (the timestamp is optional).

    –or-

    If you just want to sign the cabinet file, with the Visual Studio test certificate, click Use Test Certificate. This certificate is for testing purposes only. Contact an authorization company to get a certificate and private key.

  4. Click OK.


Signing a Self-Extracting Setup Distribution Unit

A self-extracting setup executable distribution unit can be signed similar to an ActiveX control. A digital signature provides accountability for software developers. The signature associates a software vendor's name with a given file. Digital signatures provide a path to you (through the company that authorized the certificate) in the event that your component causes harm on a user's system. The Microsoft development environment provides a convenient means to apply a digital signature to a self-extracting setup distribution unit.

To sign a setup executable distribution unit

  1. Display the property pages of a distribution unit.

  2. Click the Signing tab.

  3. Select the Sign Executable check box.

  4. If you have a personal certificate and private key (for example, from Verisign), click Use Certificate file, and then specify the certificate, the private key file name, and the timestamp server URL (optional).

    –or-

    If you just want to test the setup executable file, click Use Test Certificate. This certificate is for testing purposes only. Contact an authorization company to get an official certificate and private key.

  5. Click OK.


Specifying a Cabinet's Name, Friendly Name, and Version Number

A cabinet file has a file name, friendly name, and a version number. These attributes are used by the Internet Explorer code download and by the Java Package Manager. With the Microsoft development environment, you can specify these attributes for your cabinet files.

To specify the file name, friendly name, and version number of a cabinet file

  1. Display the property pages of a distribution unit.

  2. In the Cabinet Properties tab, you can specify the file name, friendly name, and version number of the cabinet file.

  3. You can also set the compression algorithm used.

  4. Click OK.


Specifying External Dependencies for a Cabinet (.cab) Distribution Unit

Cabinet files contain links to other cabinet files on the intranet or Internet. You can publish reusable components, such as system libraries, to the intranet or Internet, and then reference the reusable components in your cabinet files when needed.

When you specify that one cabinet file has a dependency on another cabinet file, the contents of the first cabinet will only be run once the contents of both cabinets are installed on the customer's computer. This is a feature of Internet Explorer code download.

You can add references to any self-installing cabinet file by specifying the URL, friendly name, and version of the cabinet file.

To specify an external dependency file for a cabinet distribution unit

  1. Display the property pages of the distribution unit.

  2. Click the External Dependencies tab.

  3. In the External Dependencies dialog box, click Add to place a new entry in the Dependencies on the Web list. Specify the URL, friendly name, and version of the required cabinet file. Click OK.

  4. Click Edit to change any entries in the Dependencies on the Web list.

  5. Click Delete to remove any entries in the Dependencies on the Web list.

  6. Click OK.


Solution Building and Packaging User Interface Reference

This section includes reference information on items in the Microsoft development environment you can use to package your solution or projects. Select any of the links below for more information on the named item.

ActiveCfg Property

Add Additional Files Dialog Box

Add/Edit External Dependencies Dialog Box

Authentication (Security – Options Dialog Box)

Cabinet (.cab) File Properties Dialog Box

Custom (Utility Project Properties Dialog Box)

Deployment (Project Properties Dialog Box)

External Dependencies (CAB Properties Dialog Box)

Java Permissions (CAB Properties Dialog Box)

Launch (Utility Project Properties Dialog Box)

Microsoft System Libraries (Setup Properties Dialog Box)

Nested Setups (Setup Properties Dialog Box)

Remote Components (Setup Properties Dialog Box)

Signing (Setup Project Properties Dialog Box)

System Directory Installation (Setup Project Properties Dialog Box)

Target (Setup Project Properties Dialog Box)

Output Format (Project Properties Dialog Box)

ZIP (.zip) Package Properties Dialog Box


ActiveCfg Property

Specifies the solution's build configuration.

Settings

The settings for the ActiveCfg property are:

  • Debug — Specifies that projects are built so that they can be debugged.

  • Release — Specifies that projects are built without any debug information.


Add Additional Files Dialog Box

Use this dialog box to add files to be packaged into a distribution unit (cabinet, setup, or Zip). You can use Add Items from the Project menu as well. This dialog box is only available from a Visual J++ project properties dialog box, Output Format tab, by clicking Include Additional Files.

Options

Add

Displays the Browse for Package Output File dialog box. You can choose the file you wish to add to the list.

Delete

Removes the selected file from the list of the files to be included in the package. Does not delete the file from your computer.

Select additional files to include in the package

Displays the list of the files you can add to the package, along with their paths. These path names refer to the file's location and are removed from the files when the files are added to the distribution unit.

To add files to the list, click Add. These files will be added to your package when you click OK. You can select many files at once in the list by clicking and dragging the mouse.


Add/Edit External Dependencies Dialog Box

Use this dialog box to specify the location of a cabinet file for which the cabinet file you are building has a dependency on the Internet or intranet.

For example, if you are building a set of Visual J++ classes that require a library to be installed on your user's computer, that library is the dependency. You can specify the location of that dependent library using this dialog box. Whenever a user downloads the cabinet file that you are building, Microsoft Internet Explorer will download the dependent library if it is not already installed on the user's computer.

Dependency files are packaged in cabinet files. The reference to the required dependency is in the form of a URL where the cabinet file is posted, the cabinet file's friendly name, and a version number (optional). The version number helps Internet Explorer know when a download of a more recent version is required.

Options

Dependency URL

Provides a place to enter or edit the location of the cabinet file containing the required dependency files. This must be a fully qualified URL, formatted with the protocol prefix (such as HTTP, HTTPS, FTP, or file).

Note If you are using deployment, a feature of the Enterprise edition, the URL for the dependency file is not updated when deploying.

Friendly Name

Provides a place to enter or edit the friendly name of the dependency file. This is the name that will appear in the Downloaded Program Files folder.

Version

(Optional.) Provides a place to enter or edit the version number of the dependency file. This is in the format of #,#,#,#. This specifies the minimum version number required for the cabinet file to run.


Authentication (Security - Options Dialog Box)

Use this dialog box to specify the default values used for signing cabinet files and setup files (distribution units). You can specify the certificate to use by default when signing cabinet and setup files. These values can be overwritten in the individual settings dialog boxes for the cabinet and setup files.

These signing options are also used when you deploy server-side components (COM components and Java classes that run on the Web server/deployment target). The development environment uses the signature file specified here when the deployment target requires that all components be signed before they can be installed on the deployment target.

Options

Certificate file

Provides a place to enter or edit the location of the certificate file (.spc) you want to use to sign this distribution unit. To locate an existing certificate file, click Browse. To get a certificate file, contact a certificate file provider.

Private Key File

Provides a place to enter or edit the location of the private key file (.pvk) associated with this certificate.

Sign Cabinet

Specifies that the distribution unit should be signed. If you sign a distribution unit, you identify yourself to the user before they download the software. Signing also verifies that the file has not been tampered with since you signed it.

Timestamp server URL

Provides a place to enter or edit the location of a timestamp server. A timestamp server validates the date and time that the distribution unit was signed. Certificate files can expire after a certain period of time. Contact your certificate file provider (certificate authority) for the location of their timestamp server.

Use defaults

Resets the distribution unit signing options to the development environment's default values set in the Tools menu, Options dialog box, Security node.

Use test certificate file

Signs the distribution unit with the Microsoft® Visual Studio™ test certificate. The Visual Studio test certificate is provided to support test scenarios only, and should not be used for signing distribution unit files that you deploy to an intranet or the Internet. The text for the Visual Studio test certificate indicates that the user should not trust the signed component based on the test signature.

Use certificate file

Enables the use of a personal or corporate signature file (certificate) to sign the distribution unit.


Cabinet (.cab) File Properties Dialog Box

Use this dialog box to specify or change the settings for the cabinet (.cab) project.

Options

Cabinet file name

Provides a place to enter or edit the file name for the cabinet file. This is the name of the cabinet generated when you build.

Certificate file

Provides a place to enter or edit the location of the certificate file (.spc) you want to use to sign this cabinet file. To locate an existing certificate file, click Browse. To get a certificate file, contact a certificate file provider (certificate authority).

Compression

Displays the current compression algorithm used to compress the cabinet file. There are four options: None, MSZip (the default), Quantum, or LZX.

Friendly name

Provides a place to enter or edit the friendly name of the cabinet file. The friendly name appears in the Windows Downloaded Program Files folder when the contents of the cabinet file are installed on your user's computer. The default friendly name is the project name used in the development environment. Alphanumerics, spaces, and dashes are legitimate characters to enter here.

Classes in this cabinet can only be called by trusted Java classes

Marks the packages in the cabinet file so that the Java classes in the packages can only be used by other trusted Java classes.

Java classes in packages with this property can only be directly used by either system classes (which are implicitly fully trusted) or classes that have been loaded by Internet Explorer 4.0 and marked as fully trusted (for example, signed CAB with low permissions). This security check is made at the time the classes are run. This prevents a set of classes from being directly used by untrusted applets.

Classes in this cabinet are globally available

Marks the packages in the cabinet file so that the Java classes in the packages can be loaded directly by the Microsoft Virtual Machine for Java (VM). Specifically, the WJView and JView utilities can load the Java classes in these packages.

Selecting this check box controls how the packages in the cabinet file are installed into the Java Package Manager. You should use this check box where traditionally you would have installed these packages on the Java CLASSPATH.

If you select this check box, you must sign your cabinet file with Java permissions at the Low level. You can set your Java Permissions on the Java Permissions tab (on the cabinet property pages).

Private Key File

Provides a place to enter or edit the location of the private key file (.pvk) associated with this certificate.

Sign Cabinet

Specifies that the distribution unit should be signed. If you sign a distribution unit, you identify yourself to the user before they download the software. Signing also verifies that the file has not been tampered with since you signed it.

Timestamp server URL

Provides a place to enter or edit the location of a timestamp server. A timestamp server validates the date and time that the cabinet file was signed. Certificate files can expire after a certain period of time. Contact your certificate file provider (certificate authority) for the location of their timestamp server.

Use Defaults

Resets the cabinet signing options to the development environment's default values set in the Tools menu, Options dialog box, Security node.

Use test certificate file

Signs the cabinet file with the Visual Studio test certificate. The Visual Studio test certificate is provided to support test scenarios only, and should not be used for signing cabinet files that you deploy to the intranet or Internet. The text for the Visual Studio test certificate indicates that the user should not trust the signed component based on the test signature.

Use certificate file

Enables the use of a personal or corporate signature file (certificate) to sign the cabinet file.

Version

(Optional.) Provides a place to enter or edit the version number of the cabinet file's contents. This is in the format of #,#,#,#. This is used by Internet Explorer to determine if the cabinet file needs to be downloaded when a version of the file already exists on the user's computer.


Custom (Utility Projects Settings Dialog Box)

Use this dialog box to specify the build engine and project outputs to be generated for the files contained within a utility project. You can place any types of files in a utility project, and then specify the command line to execute to process those files.

The project outputs of the utility project can be used in other types of projects, such as cabinet files and setup executables, if you specify the project output file names here.

You can list any type of command here, whether the command builds a file or not. Project outputs are optional. You can set the order that the Microsoft development environment uses to execute the build commands in the Build Order dialog box.

You can also use this dialog box to set random files as project output files to be included in a packaging project. For example, you can add 10 external bitmap files to the project outputs in a utility project, and then include the utility project in a cabinet (.cab) file. The external files will be packaged into the cabinet file.

Options

Build commands

Provides a place to enter the command line build commands to execute. List the full path to the build tool and files to be built here. Alternatively, the development environment will look in the current directory for the build tool or check the environment variables specified in the full path.

For example, your build command could be:

nmake C:\myproj\myproj.mak

Build outputs

Provides a place to enter the full path and file name for the project outputs generated by the build commands if you wish these project outputs to be recognized by other projects in the development environment for packaging or deployment. Build outputs information is optional.

For example, you could list C:\myproj\myproj.exe. Do not use wildcard characters, such as *.exe.


Deployment (Project Properties Dialog Box)

Use this dialog box to filter the outputs of your project for deployment after the project is built. The outputs of a project are the set of files that are required at run time to run the project.

Options

These project outputs

Specifies that only the selected (checked) output files are propagated when the project is deployed. These project outputs are not placed inside the package, but are transported with the package in deployment situations.

The complete and current list of project outputs may not appear until after you have completed a build. If the complete list of project outputs is not displayed, try rebuilding the project.

Outputs of type

Filters the files that will be deployed by file extension. Choose the output files you want, by file extension, from the drop-down list.

You can choose from the categories in the following list to filter the possible output files.

  • Distribution Units (*.cab, *.zip)

  • Java Classes and Resources (*.class, *.tlb, *.res, *.resources, *.ico, *.gif, *.jpg, *.bmp)

  • Java Classes and Web Files (*.class, *.ocx, *.htm, *.html, *.asp, *.gif, *.jpg, *.bmp)

  • Java Classes (*.class)

  • Java Classes and Sources (*.class, *.java)

  • Windows Binaries (*.exe, *.dll, *.tlb, *.ocx)

  • Windows Binaries and Resources (*.exe, *.dll, *.tlb, *.ocx, *.res, *.resources, *.ico, *.gif, *.ico, *.jpg, *.bmp)

You can also type in your own filter for the output files.


External Dependencies (CAB Properties Dialog Box)

Use this dialog box to specify that the components in the cabinet file that you are building contain dependencies on other cabinet files that may be located on the intranet or Internet.

Options

Add

Displays the Add/Edit External Dependency dialog box, where you can add an external dependent cabinet's URL, friendly name, and version number.

Delete

Removes the selected dependency entry from the list of Dependencies on the Web.

Dependencies on the Web

Displays the list of your dependency cabinet files. For each dependent cabinet file, you can see the friendly name, URL, and version number.

Edit

Displays the Add/Edit External Dependency dialog box, where you can edit the external dependent cabinet's URL, friendly name, and version number.


Java Permissions (CAB Properties Dialog Box)

Use this dialog box to specify the set of permissions requested for the signed classes in the cabinet file. This security/permissions information is used to present to the user a single dialog box that displays all the proper trust questions before any code from your cabinet is run on their computer. The dialog box can also accurately warn your user about the risk of each requested permission. This is because the set of permissions is fully defined and understood by the Microsoft® Win32® Virtual Machine (VM) for Java.

Options

Contains ActiveX Controls

Specifies in the signature that your cabinet contains Microsoft® ActiveX® controls so that the ActiveX controls will run in your cabinet.

Permission Level

Sets the cabinet file's permission level. This information is passed to the browser when the .cab file is scanned for signing upon being downloaded. There are four levels of security, as described in the following list.

  • Low A browser zone set with the "Low" setting is the least secure. This allows a signed cabinet file to have as much access to the target computer as the signed cabinet file asks for.

  • Medium A browser zone with the "Medium" setting is moderately secure. It will allow applets in signed cabinet files to have access to scratch space if the applets ask for it. (Scratch space is storage on the client machine that an applet can safely access without needing full access to the client file system.) Applets signed with medium permissions may also call user-directed file I/O routines. These routines will present dialog boxes to the user and ensure that all file operations are done with user intervention.

  • High A browser zone with the "High" setting is the most secure. It will allow applets in signed cabinet files to run in the "sandbox" (a protected space that prevents the applet from accessing files and selected system services).

  • Custom Enables the Permissions listing to select specific abilities for this .cab file.

Permissions

Displays a list of the individual permissions that can be added when you sign this cabinet file. If you set the permission level to Custom, you can select items in the list to match the permissions needed by the contents of your cabinet file.

Sign Cabinet with Java Permissions

Specifies that the cabinet file should be signed with Java permissions.


Launch (Utility Project Settings Dialog Box)

Use this dialog box to specify the debugger to run when the active project is triggered in a build (F5) action.

You can set the order that the Microsoft development environment uses to execute the build commands in the Build Order dialog box.

Options

Arguments

Provides a place to enter any command line arguments for the debugger you want to run when the active project is built.

Program

Provides a place to enter the full path name for the debugger you wish to run when the active project is built.


Microsoft System Libraries (Setup Properties Dialog Box)

Use this dialog box to add Microsoft System Libraries to your setup executable distribution unit. Add the files here to set the entire library for installation on the target computer receiving the setup distribution unit.

Simply adding these files to the setup file with the Additional Files feature will not enable the libraries to self-extract and install on the target computer as part of the setup.

Options

Description

Displays the description of the selected Microsoft System Library file.

File List

Displays the files that are placed in the setup file for the selected Microsoft System Library file. This shows the directory path where the file is coming from. You can place the cursor in this list and press the right arrow button to see the rest of the list.

Listing

Displays a list of Microsoft System Libraries available to include in the setup (.exe) distribution unit. The selected library displays the details for the name, description, and file list.

Name

Displays the name of the selected Microsoft System Library file.


Nested Setups (Setup Properties Dialog Box)

Use this dialog box to include any self-installing setup file you want to include in a setup file for execution when the setup is run on the target computer.

Simply adding these files to the setup file with the Additional Files feature will not enable the libraries to run and install on the target computer as part of the setup.

For example, the Microsoft® Visual Basic® Setup Wizard creates a setup file for any ActiveX controls authored in Visual Basic. This setup can be included in a setup file as a nested setup (a setup file inside of a setup file). When the entire nested setup is run on the target computer, the nested setups run, with the innermost setup file running first.

If these nested setup files are deployed, there are no HTML reference link updates to any but the topmost setup file.

Options

Select the programs to execute when the installer is run

Displays a list of the files you can select to nest inside your current setup distribution unit. When the entire nested setup distribution unit is run on the target computer, the innermost setup files are extracted first, and then the outermost setup distribution unit.


Output Format (Project Properties Dialog Box)

Use this dialog box to specify the format of the project outputs of a Visual J++ project. By default when a Visual J++ project is built, the Java files are compiled into .class files. Using this dialog box, you can pick the .class files, and other files, to package into a cabinet file, setup file, Zip Archive format file, COM .dll file, or a Windows .exe file. This is called in-place packaging of a project.

The project outputs may not appear until after you have completed a build.

Options

Advanced

Displays the Advanced Property Pages dialog box for the selected type of distribution unit.

Enable Packaging

Specifies that in-place packaging will be enabled when the project is built.

File name

Saves the name of the distribution unit that will be created. The default distribution unit name is the name of the project.

Include additional files

Displays the Add Additional Files dialog box, where you can add files that are not part of the immediate project but should be added to the distribution unit.

Outputs of type

Filters by file extension the files that are placed in the distribution unit. This filter is applied to all the files in your project and to all the .class files created when your project is built.

You can choose from the following categories to filter the project output files. You can also type in your own filter for the output files.

  • Distribution Units (*.cab, *.zip)

  • Java Classes and Resources (*.class, *.tlb, *.res, *.resources, *.ico, *.gif, *.jpg, *.bmp)

  • Java Classes and Web Files (*.class, *.ocx, *.htm, *.html, *.asp, *.gif, *.jpg, *.bmp)

  • Java Classes (*.class)

  • Java Classes and Sources (*.class, *.java)

  • Windows Binaries (*.exe, *.dll, *.tlb, *.ocx)

  • Windows Binaries and Resources (*.exe, *.dll, *.tlb, *.ocx, *.res, *.resources, *.ico, *.gif, *.ico, *.jpg, *.bmp)

Package Contents

Selects the contents of the distribution unit. You can pick the files that are placed in the distribution unit by filtering for the file types, or by picking the specific files. You can pick files that are not a part of the immediate project.

Packaging Type

Lists the packaging types. For the Enterprise edition, there are five possible types (other editions may have fewer packaging types available).

  • COM DLL See Visual J++ documentation for details.

  • Windows EXE See Visual J++ documentation for details.

  • Setup The self-extracting setup executable file provides a mechanism to create an installation program to distribute your standalone application to users. The setup also includes an uninstalling program.

  • CAB The cabinet file is an efficient way to package multiple files to ensure efficient download and installation of Java packages and classes executed on (or behind) HTML in the Microsoft Internet Explorer.

  • ZIP The Zip Archive (.zip) file provides a mechanism to package multiple files (such as Java packages and classes) in a single, uncompressed Zip Archive file that is compatible with Internet Explorer and other Internet browsers.

These outputs

Sets the files to be included in the distribution unit from the list. When the project is built only the selected files are included in the distribution unit.

The complete list of project outputs may not appear until you have built the project. If the list seems short, try rebuilding the project.


Remote Components (Project Properties Dialog Box)

Remote Components (Setup Properties Dialog Box)

Use this dialog box to make your setup distribution unit enter the appropriate registry entries in the target computer to enable applications to use remote objects through DCOM.

The distributed Component Object Model (DCOM) is a protocol that enables software components to communicate directly over a network in a reliable, secure, and efficient manner.

Options

Always prompt user for server

Specifies that your component's user will be asked during the installation which remote server the remote DCOM objects are running on. If you added a remote server to the Use Remote Server box, that server will be supplied as a default.

Remote Components

Displays a list of the remote DCOM files that you can select to include in the setup distribution unit. When the setup distribution unit is run on the target computer, appropriate entries are made in the registry of that target computer to enable that computer to use the remote objects through DCOM.

Use Remote Server

Provides a place to enter or edit your remote server computer's network name. The remote server is the computer that will run the remote component.


Signing (Setup Project Properties Dialog Box)

Use this dialog box to specify or change the digital signing settings for the setup executable distribution unit.

Options

Certificate file

Provides a place to enter or edit the location of the certificate file (.spc) you want to use to sign this setup file. To locate an existing certificate file, click Browse. To get a certificate file, contact a certificate file provider.

Private Key File

Provides a place to enter or edit the location of the private key file (.pvk) associated with this certificate.

Sign Executable

Specifies that the distribution unit should be signed. If you sign a distribution unit, you identify yourself to the user before they download the software. Signing also verifies that the file has not been tampered with since you signed it.

Timestamp server URL

Provides a place to enter or edit the location of a timestamp server. A timestamp server provides a validation of the date and time that the setup file was signed. Certificate files can expire after a certain period of time. Contact your certificate file provider for the location of their timestamp server.

Use certificate file

Enables the use of a personal or corporate signature file (certificate) to sign the setup file.

Use Defaults

Resets the setup file signing options to the development environment's default values set in the Tools menu, Options dialog box, Security node.

Use test certificate file

Signs the setup file with the Visual Studio test certificate. The Visual Studio test certificate is provided to support test scenarios only, and should not be used for signing setup files that you deploy to the intranet or Internet. The text for the Visual Studio test certificate indicates that the user should not trust the signed component based on the test signature.


System Directory Installation (Setup Project Properties Dialog Box)

Use this dialog box to place shared files in the Windows System directory of the target computer when the setup (.exe) extracts itself.

If you place these shared files in a different directory, the uninstaller for your setup (.exe) may not recognize when other programs share that resource file, and may inappropriately uninstall the file. Keeping all the common shared files in the same standard directory, the Windows System directory, ensures that the proper files will remain.

Options

Select the files to place into the target computer's Windows System directory

Displays a list of the files you can place in the Windows System directory when the setup (.exe) distribution unit extracts itself on the target computer. Select the files you wish to place in that directory.

This list includes files that are added as Additional Files or are project outputs.


Target (Setup Project Properties Dialog Box)

Use this dialog box to set the setup file name and the entry it will write to the Windows Start menu of the target computer.

Options

Application title

Provides a place to enter or edit the application title for the extracted application as you want it to appear in the Windows Add/Remove Programs dialog box. To reach this dialog box, click the Start menu, point to Settings, click Control Panel, and then double-click Add/Remove Programs.

Argument

Provides a place to enter or edit the argument for the command line program that you specified in the Command line program box. For example, this could be the specific HTML page you want to launch with Internet Explorer 4.0.

Command line program

Provides a place to enter or edit the command line information that runs the application when the shortcut name is used from the Windows Start menu. This information, if available, is filled in from the Launch (Project Properties) dialog box.

Create an entry in the Start menu

Specifies that the setup (.exe) distribution unit will place an entry for the application in the target computer's Start menu.

Insert Default

Inserts a variable representing a folder location on the target computer into either the Command Line or Argument text boxes (whichever box is selected). For example, if your setup installs the program "MyApp.exe," you might make the command line "<AppDir>\MyApp.exe".

You can choose from the following:

  • <AppDir> – specifies the directory where you are installing the setup distribution unit.

  • <IEDir> – specifies the installation folder for Internet Explorer 4.0.

  • <SysDir> – specifies the Windows System folder.

  • <WinDir> – specifies the Windows folder.

Installation folder

Provides a place to enter or edit the default location you want the application to install to on the target computer. (Your user can override this default value when they run the setup.)

Install under the "Program Files" folder

Specifies that the setup distribution unit will place the installation folder inside the Window Program Files folder. The development environment automatically seeks out the Program Files folder on the target computer, even in other written languages, and even if the Program Files folder is not in the default location.

Setup file name

Provides a place to enter or edit the name you want for the self-extracting setup (.exe) distribution unit.

Shortcut name

Provides a place to enter or edit the name of the application as you want it to appear in the Windows Start menu, under Programs.


ZIP (.zip) Package Properties Dialog Box

Use this dialog box to enter or edit the Zip Archive (.zip) file name.

Options

Zip file name

Provides a place to enter or edit the Zip file name. Standard file name guidelines apply.


Solution Building and Packaging Errors

<Name> could not be added

A file with the name <name> has already been added to the package.

An error occurred during packaging <name>.

An error occurred while packaging <name>

Error encountered in the format of the persisted packaging project file

Error: Failed to generate signature for CAB

Failed to generate signature for <name>, because it does not exist

Failed to generate signature for <name> (certificate file not specified)

Failed to generate signature for <name> (test certificate not found)

Failed to generate signature for <name>. See the Output Window

Failed to generate signature for <name> (test private key not found)

Failed to generate signature for <name> (private key file <name> does not exist)

Failed to generate signature for <name> (private key file not specified)

Failed to generate signature for <name> (‘javasign.dll’ can’t be found)

Failed to generate signature for <name> (no custom Java permissions)

Failed to generate signature for <name> (unknown internal error)

Failed to generate signature for <name> (‘signcode.exe’ can’t be found)

Failed to generate signature for <name> (certificate file does not exist)

If you want to create an entry in the start menu, please provide a name

In order to create an entry in the start menu, we need the command line

Internal error – packaging engine exception

Package output filename <name> was longer than 256 characters

Please fill in a value for the Installation Folder

Project outputs which are not local file URLs…

Setup Packaging Error: <name>

Setup Packaging Error: cannot create CAB for this setup

Setup Packaging Error: no input files

Setup Packaging Error: build cancelled

Setup Packaging Error: Cannot find input file

Setup packaging error: Cannot find the TLB files

Setup Packaging Error: error writing file <name>

The build configuration cannot be changed while projects are building or deploying.

The dependency <name> has already been added to the dependency list

The file <name> does not exist. Add to distribution unit anyway?

The file <name> has already been added to the distribution unit

The file <name> from source <name> conflicts with a file

The project you are removing is referenced by project

The input field for the installation directory is not a valid path

The optional redistributable files for the installer are not installed

The referenced project, <name>, is not active within the solution

The URL and Friendly name fields are required

The version number <name> is not in the correct format

Unable to load the required packaging engine

You have not applied pending changes to the currently selected configurations.


<Name> could not be added

The Microsoft development environment could not locate one of the files to add to a Zip Archive Format file.

Try the following:

  • Confirm that the file exists and is located in the correct directory.

  • Confirm that your project outputs built correctly.


A file with the name <name> has already been added to the package.

The file you are adding to a distribution unit has a name that matches a file name already in the distribution unit.

Check to see if the files are the same. Rename one of the files if they are not.


An error occurred during packaging <name>.

The Microsoft development environment cannot complete the packaging action. You can try the packaging action again, restart the development environment, or reboot your computer.


An error occured while packaging <name>

An error occurred while packaging <name>

The Microsoft development environment is creating a Zip Archive Format file and cannot open the .zip file.

Confirm the output format file name for the .zip file.


Error encountered in the format of the persisted packaging project file

The Microsoft development environment cannot load the packaging project file (.pkp) due to corruption in the file format.

Try the following:

  • Remove custom edits to the .pkp file, or revert to an earlier version of the .pkp file.

  • Create a new packaging project and add your files.


Error: Failed to generate signature for CAB

The Microsoft development environment could not find or run Signcode.exe, which creates the signature for the cabinet file.

Try the following:

  • Reinstall Visual Studio with the Visual Studio Installation Wizard.

  • Reinstall the Java.sdk.


Failed to generate signature for <name>, because it does not exist

The file you are trying to sign is not where the Microsoft development environment expected it to be.

Try the following:

  • Confirm that your distribution unit built properly.

  • Check file permissions on the package output file (cabinet or setup).


Failed to generate signature for <name> (certificate file does not exist)

The Microsoft development environment could not locate a certificate file.

Try the following:

  • Check the spelling of the certificate file name.

  • Confirm the file's path.


Failed to generate signature for <name> (certificate file not specified)

There was no certificate file for the Microsoft development environment to use in the signing process.

Specify a certificate file in the Property pages of a Visual J++ project (Output Format tab), or in the Tools menu, Options dialog box, in the Security node.


Failed to generate signature for <name> ('javasign.dll' can't be found)

The Microsoft development environment could not locate the javasign.dll to finish the signing process.

Try reinstalling the Java SDK or Visual Studio.


Failed to generate signature for <name> (no custom Java permissions)

The Microsoft development environment did not get enough information on which custom Java permissions to set for the package.

Specify the exact custom Java permissions in the dialog box where you selected Custom for Java permissions.


Failed to generate signature for <name> (private key file <name> does not exist)

The Microsoft development environment could not locate the private key file specified.

Try the following:

  • Confirm that the file name and the path specified in the Outputs tab or the Options dialog box (Tools menu, Options, Security node).

  • Confirm that the file is in the proper location.


Failed to generate signature for <name> (private key file not specified)

The Microsoft development environment could not locate the certificate file and key files because more information is needed.

Enter the location of the certificate file and private key file.


Failed to generate signature for <name>. See the Output Window

The Microsoft development environment could not complete the signing operation. See the Output Window for the details.


Failed to generate signature for <name> ('signcode.exe' can't be found)

The Microsoft development environment could not locate Signcode.exe, which is needed to complete the signing process.

Try the following:

  • Confirm that Signcode.exe is on your path environment variable in Windows.

  • Reinstall the Java SDK.

  • Reinstall Visual Studio.


Failed to generate signature for <name> (test certificate not found)

The Microsoft development environment could not find the test certificate included with Visual Studio.

Try reinstalling Visual Studio with the Visual Studio Installation Wizard.


Failed to generate signature for <name> (test private key not found)

The Microsoft development environment could not find the test private key included with Visual Studio.

Try reinstalling Visual Studio with the Visual Studio Installation Wizard.


Failed to generate signature for <name> (unknown internal error)

There was an internal problem with the Microsoft development environment signing process.

Try the following:

  • Attempt the operation again.

  • Reboot your computer.

  • Reinstall Visual Studio.


File already in Distribution Unit


If you want to create an entry in the start menu, please provide a name

The Microsoft development environment could not find specific information on the name of the application to place in the Windows Start menu item, as noted in the property pages for the packaging project.

Try the following:

  • Specify the application's name.

  • Check the spelling of the application's name.


In order to create an entry in the start menu, we need the command line

The Microsoft development environment could not find specific information on the name of the application to start from the Windows Start menu item, as noted in the property pages for the packaging project.

Try the following:

  • Specify the command line for the application.

  • Check the spelling of the application's name.


Internal Error - Packaging Engine Exception

The Microsoft development environment cannot finish the packaging task due to an internal problem.

Try closing down Visual Studio and rebooting your computer.


Package output filename <name> was longer than 256 characters

The package output file name is too long. The maximum length of the output file name can be 256 characters (including the file path).


Please fill in a value for the Installation Folder

The Microsoft development environment could not find any installation folder specified in the Target property page for a setup package.

Specify a folder in which to install the setup on the Target property page.


Project outputs which are not local file URLs...

The Microsoft development environment encountered an internal error and cannot recover.

Try rebooting your computer.


Setup Packaging Error: build cancelled

The Microsoft development environment encountered internal errors and the build was cancelled before it was started.

Try rebooting your computer and building again.


Setup Packaging Error: cannot create CAB for this setup

The Microsoft development environment could not finish the setup building process because the .cab file for the setup could not be created in your temporary directory.

Try the following:

  • Check your temporary directory for adequate disk space, and try to build the setup again.

  • Reboot your computer.

  • Reinstall Visual Studio.


Setup packaging error: Cannot find input file

The Microsoft development environment could not locate the .vbr file needed to match a .tlb file added to a nested setup file.

Confirm that the .vbr file was added to the setup packaging project, and that the file is in the proper location.


Setup packaging error: Cannot find the TLB files

The Microsoft development environment could not locate the .tlb file needed to match a .vbr file added to a nested setup file.

Confirm that the .tlb file was added to the setup packaging project, and that the file is in the proper location.


Setup Packaging Error: error writing file <name>

The Microsoft development environment could not create a temporary .dat file needed to create the setup package because there was an error writing the file to the temporary directory.

Check that the temporary directory exists and has the appropriate read/write settings.


Setup Packaging Error: <name>

The Microsoft development environment encountered a problem building the setup file.

Check all the settings for the setup. Try rebuilding the project outputs for the setup, rebooting your computer, and packaging again.


Setup Packaging Error: no input files

The Microsoft development environment tried to create a setup with no files specified to add to it.

Check that all the projects build correctly and that the project outputs are specified in the setup property pages.


The build configuration cannot be changed while projects are building or deploying.

The Microsoft development environment cannot change the configuration (either debug or release) while building or deploying. Wait until your build or deployment is complete, then change your configuration.


The dependency <name> has already been added to the dependency list

The Microsoft development environment located an external dependency that matches the friendly name and URL of the external dependency you just entered.

Try a different friendly name and URL for an external dependency.


The file <name> does not exist. Add to the distribution unit anyway?

The Microsoft development environment could not locate the file you specified in the Browse dialog box, in the process of adding a file to an in-place packaging project.

Try locating the file again, and check the spelling of the file name.


The file <name> from source <name> conflicts with a file

Two files of the same name were put into the same package (sometimes from different projects).

Rename one of the project outputs or files.


The file <name> has already been added to the distribution unit

The Microsoft development environment finds a file name that matches the file name you provided in the Output Format dialog box (Visual J++ property pages), in the Include Additional Files dialog box.

Try adding a different file or confirm that the file contents are the same.


The input field for the installation directory is not a valid path

The Microsoft development environment requires valid characters in the Installation Folder field of the Target property page Tab for a setup project.

Illegal characters are /,*,?,”,>,<,| and ;.


The optional redistributable files for the installer are not installed

The Microsoft development environment could not locate the redistributable files (such as system libraries) for the setup package.

Reinstall Visual Studio to get the redistributable files.


The project you are removing is referenced by project

The Microsoft development environment found a project reference (a project output) to a project that was removed from the packaging project.

Since the project that generated this output reference was deleted, you should delete the reference as well.


The referenced project, <name>, is not active within the solution

The packaging project is referencing project outputs from a project that is not within the same solution.

Remove any project outputs from the packaging project that refer to deleted projects.


The URL and Friendly Name fields are required

The Microsoft development environment could not locate the friendly name and URL information for an external dependency.

Check the external dependency and add the information to the External Dependency property page.


The version number <name> is not in the correct format

The version format supplied does not match #,#,#,#. These numbers should be integers.

Specify a version in integers on the External Dependencies Tab or the Output Format property pages of a project.


Unable to load the required packaging engine

The project file specifies a packaging engine type unavailable in this edition.

Try the following:

  • Turn off the packaging.

  • Add packaging by upgrading a version.


You have not applied pending changes to the currently selected configurations.

The Microsoft development environment cannot change the configuration (either debug or release) while there are changes that are unapplied from your current dialog box. If you choose Yes, the changes are applied to the new configuration you selected. If you choose No, the configuration is changed to the one you selected, but all the changes in the dialog box are dropped. If you choose Cancel, you are returned to your original configuration with all the changes still unapplied in the dialog box.


Solution Deployment Reference

With deployment features of the Microsoft development environment, you can more easily distributed and debug the components of your Web applications. From within the environment, you can specify target computers for your components, then deploy those components in the configurations that best suit your needs.

The following sections provide information to acquaint you with deploying applications in the Microsoft development environment.

Section | Description
Solution Deployment Concepts | Introduces concepts key to deploying your applications with the Microsoft development environment (for Microsoft® Visual J++™ and Microsoft® Visual InterDev™).
Solution Deployment Common Tasks | Provides links to step-by-step instructions for performing common deployment tasks.
Solution Deployment User Interface Reference | Provides links to topics describing what you'll see in dialog boxes associated with deployment.
Solution Deployment Error Messages | Provides links to topics describing error messages you may encounter when deploying your applications.


Solution Deployment Concepts

With the Microsoft development environment (for Microsoft® Visual J++™ and Microsoft® Visual InterDev™), you can deploy your projects to Web servers for testing and production. You can set up more than one target machine to deploy to, and arrange your files in the Deployment Explorer to match the needs of those configurations.

Note The examples in this section refer to Visual J++ as the main coding application. If you are using Visual InterDev for coding and need to copy an entire Web, please see the Visual InterDev documentation.

The following sections provide information to acquaint you with deployment in the development environment.

Section | Description
Application Deployment in Visual Studio | Provides a brief description of the steps to deploying, as well as the two types of deployment.
Setting Up a Web Server for Deployment | Describes the process for configuring your Web server to deploy Web content and server-side components.
Configuring a Deployment Target | Describes the process for contacting the Web server and displaying the services available to that deployment target.
Generating and Placing Project Outputs | Introduces how you can arrange your files and outputs for deployment targets and services.
HTML Tags Updated During Deployment | Provides an overview of the updates that the development environment makes to HTML tags referring to Java classes you deploy.
Using Deployment to Deploy and Debug Web Applications | Introduces using your deployment target for deploying Web applications and debugging those applications remotely.


What Is Deployment?

Application Deployment in Visual Studio

Through deployment, you can get your application to the platforms on which it needs to run. This topic introduces how you can:

  • Set up a server as a deployment target.

  • Configure your deployment targets.

  • Generate and place project outputs.

  • Understand HTML tags updated during deployment.

  • Use deployment to distribute and debug Web applications.

Web Server Setup for Deployment

To deploy to another machine, a Web server, you may need to install additional software on the Web server. If the Web server is running Microsoft® Internet Information Server (IIS) or the Personal Web Server (PWS), you can deploy Web contents, controls, and applets with no further configuration work on that server.

If you want to deploy server-side components, however, you should confirm that the Web server has Microsoft® Posting Acceptor 2.0 installed from Microsoft® Visual Studio™ or Microsoft® Visual J++™. This enables the Microsoft development environment to deploy server-side components to that Web server.

To deploy Web content to a Web server, you need read/write access to the Web server. The administrator of the Web server can set more detailed control on access privileges and security settings.

Configure Your Deployment Targets

After your Web server is up, you can specify it in a URL given to a deployment target. The development environment will check the Web server to see if the server can handle server-side components or just Web contents, controls, and applets. You can create as many deployment targets as you like.

Generate and Place Project Outputs

Once your deployment targets are created, you can add project outputs or additional files. Project outputs are items generated by a build — such as the outputs of a Visual J++ applet project: the HTML pages and Java class files. Additional files are files copied to the deployment target URL — such as a Readme.txt file added to the deployment target for that configuration.

HTML Tags Updated During Deployment

The Microsoft development environment deployment feature performs all required updates to the deployed HTML referencing deployed Java classes so that changing the location of the file, through deployment, will not break the HTML link. The updated HTML is only the deployed HTML on the Web server, not the HTML code saved in your project.

Deployment for Distributing and Debugging Web Applications

You can create a deployment target that will deploy your application to the production Web server. Whenever you need to deploy the application into production you can select the Deploy command, and the development environment will deploy the application. Thus you can periodically redeploy your application as changes are made and tested.

You can debug the deployed application remotely, as the application responds to breakpoints set on your own computer.

For More Information For step-by-step instructions on performing tasks introduced in this topic, see the following topics.

  • Setting Up a Web Server Setup for Deployment

  • Configuring a Deployment Target

  • Generating and Placing Project Outputs

  • HTML Tags Updated During Deployment

  • Using Deployment to Distribute and Debug Web Applications


Setting Up a Web Server For Deployment

To deploy items from one machine to another requires that the deployment target be valid. A valid deployment target is a computer set up as a Web server with specific software, such as Microsoft Internet Information Server (IIS) or Microsoft Personal Web Server (PWS). This receiving Web server can be configured with a variety of Web server software, but the best performance comes from using IIS and PWS.

With Microsoft software you can:

  • Configure your Web server for Web content, controls, and applets.

  • Configure your Web server for server-side components.

  • Deploy to computers using Web server software not offered by Microsoft.

Configure Your Web Server for Web Content, Controls, and Applets

With IIS or PWS installed on your Web server, you can deploy Web content, applets, and controls with no further configuration. You can install IIS or PWS (available for Microsoft® Windows NT® Server or Microsoft® Windows NT® Workstation, respectively) as your target Web server software from the Windows NT Option Pack.

Configure Your Web Server for Server-Side Components

In addition to the basic deployment of Web content, controls, and applets, you can also deploy server-side components. Examples of server-side components are .asp pages and COM components. To set up your Web server for server-side components, you need to install the Microsoft® Posting Acceptor 2.0 on the Web server. You also need to do some additional configuration steps to your IIS or PWS server to allow content to be written to that Web server.

For step-by-step instructions, see Installing IIS on a Web server.

Microsoft Posting Acceptor 2.0 ships with Visual Studio and Visual J++, and can be installed from the server setup.

Note Earlier versions of Posting Acceptor (earlier than Posting Acceptor 2.0) do not support the deployment of server-side components.

Deploying to Computers Using Web Server Software Not Offered by Microsoft

The development environment uses the Microsoft Web Publishing Wizard API to deploy components to Web servers. With this API you can also deploy client-side Web content to computers using Web server software not offered by Microsoft. For information about how to configure a non-Microsoft Web server as a deployment target, see the search for Microsoft Web Publishing Wizard home page at the Microsoft Web site at http://www.microsoft.com.


Configuring a Deployment Target

In the Microsoft development environment, you can set up one or more deployment targets that describe your application configuration in its deployed state on the Web server. The development environment helps you to:

  • Set up a deployment target.

  • Find services for a deployment target.

  • Add files to the two service nodes.

Setting Up a Deployment Target

If you have configured a Web server computer for deployment, you can identify the Web server's HTTP address in the Microsoft development environment. A deployment target displays the URL of the Web server and also describes the services available on that Web server.

There are two services available to a deployment target: Web Content, Controls & Applets and Server-Side Components. As a service, Web Content, Controls & Applets handles components that run in the Web browser. The Server-Side Components service handles components that run on the Web server itself.

The server-side components can be deployed to Web servers that have either the Internet Information Server (IIS) or the Personal Web Server (PWS) installed, along with Posting Acceptor 2.0.

You can create one or more deployment targets in your solution. Each deployment target can correspond to a different deployment configuration or a different deployment URL. You can browse, maintain, or remove deployment targets using the Microsoft development environment's Deployment Explorer window.

Each deployment target is associated with a single URL, which is the destination to which all files and projects in the deployment target are deployed. This URL is the root node to which files and projects will be deployed. If your project contains any folders, these folders will be deployed below the target root node.

For example, if your Visual J++ project contains a folder called "MyPackage" and you deploy the project to http://TestServer/Projects, the items in the MyPackage folder will be deployed to http://TestServer/Projects/MyPackage. The default name of a deployment target reflects the target's URL. In the example, the deployment target's name would be "Deploy to http://TestServer/Projects."

Finding Services for the Deployment Target

Deployment targets can contain two services.

  • Web Content, Controls & Applets that handle HTML pages, ActiveX controls, WFC classes, and Java applets. These components run in the customer's browser.

  • Server-Side Components that handle ASP pages, COM components, and Java classes. These components are designed to run on the Web server.

To accept deployment of server-side components, the Web server must have either the Microsoft Internet Information Server (IIS) or Microsoft Personal Web Server (PWS) installed, as well as Posting Acceptor 2.0.

The Microsoft development environment will check the deployment target when you supply the URL to see if that deployment target can support server-side components. If the deployment target is a Web server with the appropriate software installed, the Server-Side Components node will appear in the deployment target's node in the Deployment Explorer window.

How to Add Files to the Two Service Nodes

Deployment targets contain references to the projects and files that you want to be deployed. In the Deployment Explorer you can see the projects and files that will be deployed listed under each deployment target.

To add files to a service node of a deployment target so that the files can be deployed, select the service node, either Web Content, Controls & Applets, or Server-Side Components, and select Add Project Outputs or Add Item from the Project menu.

Once the files are listed in the appropriate service node, you can choose Deploy from the Project menu to deploy that deployment target.


Generating and Placing Project Outputs

After you've set up the Web server, and identified the deployment target in the Microsoft development environment, you can set up the files or outputs to deploy to that deployment target. When preparing for deployment, you should understand:

  • What project outputs are.

  • What files will be deployed.

  • How to deploy project outputs.

  • How a Visual InterDev project is deployed.

What Are Project Outputs?

The "outputs" of a project are the files required at run time to run the project. For example, the outputs of a Visual J++ applet project would be the HTML pages and Java class files.

What Files Will Be Deployed?

A deployment target can contain both project outputs and files that do not require a building process, for example, a Readme.txt or a Picture.gif file. If you add a non-building file to a deployment target, that file is copied to the deployment target's URL.

How to Deploy Project Outputs

To deploy the outputs of a project, you can add the project to a deployment target, and then select Deploy from the Project menu. The outputs of that particular project are set in the property pages for that project.

For example, the outputs of a Visual J++ project can be specified either by file name or by file type (such as the file extension, *.class). You can specify the outputs on the Project Properties dialog box, on the Deployment Property tab. By selecting items in this tab, you can control which files are deployed.

How a Visual InterDev Project Is Deployed

You cannot modify the outputs of a Visual InterDev project. When you deploy a Visual InterDev project, the entire Visual InterDev Web site is copied and installed to the URL specified in the deployment target.


HTML Tags Updated During Deployment

The Microsoft development environment deployment feature performs all required HTML updates to deployed HTML that references deployed Java classes so that changing the location of the file, through deployment, will not break the HTML link. Only the deployed HTML is updated on the Web server, not the HTML code saved in your project.

When considering deployed HTML, you should understand:

  • What HTML tags need updating.

  • HTML references to cabinet or Zip files that contain Java class files.

  • Updates made to a Zip file.

  • Updates made to a cabinet file.

What HTML Tags Need Updating

You can create HTML that references a Java class, such as a Java class behind HTML or a Java applet hosted on an HTML page. When you deploy this HTML reference tag and classes to a Web server, the Microsoft development environment will modify any <APPLET> or <OBJECT> tags in the deployed HTML to ensure that they reference the deployed classes in the correct location.

The deployment feature will add a CODEBASE parameter to all <APPLET> and <OBJECT> tags that reference deployed Java classes. The CODEBASE parameter will specify the deployed location of the Java class. This ensures that the deployed HTML is always able to access the deployed Java classes.

HTML References for Cabinet or Zip Files That Contain Java Class Files

You can also create cabinet files and Zip files that contain Java classes. When you deploy cabinet or Zip files that contain Java class files and HTML files that reference those classes, the Microsoft development environment will modify any <APPLET> or <OBJECT> tags in the deployed HTML to ensure that they reference the deployed cabinet or Zip files in the correct location.

Updates Made to a Zip File

The deployment feature will add an ARCHIVE parameter to all <APPLET> tags that reference Java classes that have been deployed in a Zip file. The ARCHIVE parameter specifies the deployed location of the Zip file.

Updates Made to a Cabinet File

The deployment feature in the development environment will add a CABBASE parameter to all <APPLET> and <OBJECT> tags that reference Java classes that have been deployed in a cabinet file. The CABBASE parameter specifies the deployed location of the cabinet file.

Deploying will also add a set of USESLIBRARY parameters (in place of the CABBASE parameter) to all <APPLET> and <OBJECT> tags that reference for Java packages (as opposed to Java classes) that have been deployed in a cabinet file. The USESLIBRARY parameters specify the deployed location of the cabinet file, and the version and friendly name so that the Java packages in the cabinet file can be installed into the Java Package Manager.


Using Deployment to Deploy and Debug Web Applications

With the Microsoft development environment, you can deploy your Visual J++ and Visual InterDev projects to Web servers. This kind of deployment supports two important development scenarios:

  • Testing and debugging Web applications in their deployed configuration on remote servers.

  • Deploying Web applications to a production Web server so that users and testers can use the application.

With the development environment, you can manage and configure several deployment targets, which means that you can deploy your application in a number of different configurations to a number of different Web servers.

Debugging Applications on Remote Servers

With the Microsoft development environment, you can debug applications in which components are targeted for deployment across machine boundaries. For example, if you are developing a Web application that contains components that run in the browser and components that run on the server, you can deploy your application to a Web server, and then test and debug your application in its deployed configuration. When you are debugging the application, the application will stop on breakpoints even when they occur in code or script that is executing on a remote platform.

You can create a deployment target that describes the configuration of the application deployed on a test Web server. If you select the deployment target, and then select Set As Active on the shortcut menu, the application will be deployed and run in its deployed configuration whenever you debug the application.

Deploying Web Applications to a Production-Centered Web Server

You can use the Microsoft development environment to deploy Web applications written in Visual J++ and Visual InterDev to a production server. For example, if you are building a Web application in Visual J++, you can create a deployment target that will deploy your application to the production Web server. Whenever you need to deploy the application into production you can select Deploy on the shortcut menu, and the development environment will deploy the application. Thus you can periodically redeploy your application as changes are made and tested.

Similarly, if you are building a Web application using Visual InterDev, and your Visual InterDev project is not on your production Web server, you can use deployment to periodically deploy and redeploy your application into production. In this case the development environment will deploy the entire Web site to the production server. You can also use a deployment target to deploy a combination of Visual InterDev and Visual J++ projects.

If you use Microsoft Site Server to manage your Web site you can use the Microsoft development environment to deploy your application to a Content Replication Service (CRS) project, for subsequent replication across a Web site.


Solution Deployment Common Tasks

This section contains step-by-step instructions for the most common Microsoft development environment tasks related to deployment.

These tasks include:

Adding a New Deployment Target

Adding Projects or Files to the Deployment Target

Configuring an IIS Server to Be a Deployment Target

Deploying a Solution

Deploying Web Contents, Controls, and Applets

Deploying Server-Side Components

Displaying the Deployment Explorer Window

Removing a Deployment Target from the Solution

Removing Projects and Files from a Deployment Target

Setting the Active (Default) Deployment Target


Adding a New Deployment Target

In the Microsoft development environment, you can set up one or more deployment targets that describe your application configuration in its deployed state on a Web server.

There are two deployment services available to a deployment target: Web Content, Controls & Applets and Server-Side Components. As a service, Web Content, Controls & Applets handles components that run in the Web browser. The Server-Side Components service handles components that run on the Web server itself.

Note Only a Web server configured for server-side components contains the Server Components service in the Web server's Deployment Target node in the Deployment Explorer.

To add a new deployment target

  1. Open your solution.

  2. On the Project menu, click New Deployment Target.

  3. In the New Deployment Target dialog box, specify the URL of the target Web server in the Deploy to URL box. For example, you could enter "http://MyWebServer/SubDirectory".

  4. Select any project output files you want added to the Web Contents, Controls & Applets service node. You can add files or outputs to the Server Components service node later in the Deployment Explorer, if your Web server is configured for server-side components.

  5. Click OK.


Adding Projects or Files to the Deployment Target

Deployment targets contain references to the projects and files that you want to be deployed. In the Deployment Explorer you can see the projects and files that will be deployed listed under each deployment target.

Once the files are listed in the appropriate service node, you can deploy that deployment target.

To add a project to an existing deployment target

  1. In the Deployment Explorer, expand the deployment target.

  2. Select a service node to which you want to add your project. For example, you can choose Web Content, Controls & Applets.

  3. On the Project menu, click Add Project Outputs.

  4. In the Add Project Outputs dialog box, select the projects that you want to add to the service.

  5. Click OK.

To add a file to an existing deployment target

  1. In the Deployment Explorer, expand the deployment target.

  2. Select a service node to which you want to add your file. For example, you can choose Web Content, Controls & Applets.

  3. On the Project menu, click Add Files.

  4. In the Add Files dialog box, select the files that you want to add to the service.

  5. Click OK.


Configuring an IIS Server to Be a Deployment Target

To deploy items from one computer to another requires that the deployment target be valid. A valid deployment target is a computer set up as a Web server with specific software, such as the Microsoft® Internet Information Server (IIS) or the Personal Web Server (PWS). This receiving Web server can be configured with a variety of Web server software, but the best performance comes from using IIS or PWS.

With IIS or PWS installed on your Web server, you can deploy Web content, applets, and controls with no further configuration. To set up your Web server for server-side components, you need to install the Microsoft® Posting Acceptor 2.0 on the Web server and do some additional configuration steps to your IIS or PWS server.

The following basic steps to setting up an IIS Web server for deployment are given in more detail in this topic.

  • Install Microsoft Internet Information Server (IIS) 4.0 on the Web server.

  • Install Posting Acceptor 2.0 on the Web server. (Optional. This is for deploying server-side components.)

  • Open the IIS Management Console and locate the Web server.

  • Set write permission on the folders that you want to use for deployment on the Web server.

  • Confirm that the IIS Scripts folder has execute permission.

When you are done with these steps, your Web server is configured to receive deployment of server-side components as well as Web content.

To install Microsoft Internet Information Server (IIS) 4.0 from the Windows NT Option Pack

  1. On a computer with Microsoft® Windows NT® Server installed, install Microsoft® Internet Information Server (IIS) from the Windows NT Option Pack.

  2. Follow the directions in the installation.

To install the Personal Web Server from the Windows NT Option Pack

  1. On a computer with Microsoft® Windows NT® Workstation installed, install the Microsoft Personal Web Server (PWS) from the Windows NT Option Pack.

  2. During the setup, select Custom (rather than Minimum or Typical).

  3. In the Installation dialog box, in the Components list, select Personal Web Server. Click Show Subcomponents.

  4. Confirm that the Internet Service Manager is selected.

  5. Click OK and continue the installation.

To install Posting Acceptor 2.0 on the Web server

  • Install Posting Acceptor 2.0 on the same computer that you put IIS or PWS. You can run the installation from the Microsoft® Visual Studio™ Server Setup.

    Note If you are installing from the Microsoft® Visual J++™ CD, you must install Posting Acceptor 2.0 by running pasetup.exe from the Visual J++ CD's deploy directory.

To open the IIS Management Console and locate your Web server

  1. On the Windows Start menu, point to Programs, point to Windows NT 4.0 Options Pack, point to the Microsoft Internet Information Server, and then click Internet Service Manager.

  2. In the Microsoft Management Console, expand the Console Root node.

  3. In the Console Root node, expand the Internet Information Server node.

  4. In the Internet Information Server node, expand the IIS server node for the server you want to configure.

    Now that you've located your Web server, you can configure that Web server for deployment.

To set Write permission on the IIS folders that you want to deploy to

  1. In the IIS server node for the chosen Web server, select the Default Web Site.

  2. On the Action menu, click Properties.

  3. In the Default Web Site Properties dialog box, select the Home Directory tab.

  4. On the Home Directory tab, confirm that the Access Permissions: Write check box is selected.

  5. Click Apply.

  6. In the Inheritance Overrides dialog box, select only the folders to that these new settings will apply for deployment.

    Warning You will not be able to deploy to folders which do not have these new settings.

  7. On the Inheritance Overrides dialog box, click OK.

  8. On the Home Directory tab, click OK.

To confirm that the IIS Scripts folder has execute permission

  1. Open the IIS Management Console and locate your Web server.

  2. In the Internet Information Server node, expand the Default Web Site node. Select Scripts.

  3. On the Action menu, click Properties.

  4. In the Properties dialog box, click the Virtual Directory tab.

  5. On the Virtual Directory tab, confirm that Permissions is set to Execute (including script).

  6. Click OK.


Deploying a Solution

With the Microsoft development environment, you can manage and configure several deployment targets. The Deploy Solution command applies to the deploy target that you have set as active. The default active deployment target is the Deploy to My Computer target.

To deploy a solution

  1. Add a new deployment target.

  2. If you are deploying one or more projects, you should confirm that each project has the correct set of project outputs selected for deployment. Specify the project outputs for deployment.

  3. Add any additional files that you want to deploy. For more information, see Adding Projects or Files to the Deployment Target.

  4. On the Project menu, click Deploy Solution.

To deploy a target without changing the active target

  1. Add a deployment target to the solution.

  2. Specify the project outputs for deployment.

  3. Add any additional files that you want to deploy. For more information, see Adding Projects or Files to the Deployment Target.

  4. On the Project menu, point to Deploy, and then select the target. All the projects and files in the deployment target will be deployed.

To deploy the active deployment target when you debug a solution

  1. In the Deployment Explorer, choose the target that you want to be the active deployment target.

  2. On the Project menu, click Set as Active.

  3. On the Debug menu, click Start.

Note You can also deploy the solution without running it by clicking Deploy Solution on the Project menu.


Deploying Server-Side Components

You can deploy your projects in two main ways — as server-side components run on the Web server, or as Web components and content files that are available for downloading from the Web server. The procedure in this topic shows you how to set up a deployment configuration for a server-side component and deploy it.

The Web server must support server-side components for the service to be displayed in the Deployment Explorer. (For more information on supporting server-side components, see Setting Up a Web Server for Deployment).

The Microsoft development environment uses c:\devcache\svrcmp as the default folder on the Web server to which components are deployed. You can change the default subdirectory in the Server Components properties page (select the Server Components node, right-click, and click Deployment Target Settings).

To deploy server-side components

  1. In the Project Explorer, open the project.

  2. On the Project menu, click New Deployment Target.

  3. In the New Deployment Target dialog box, click Deploy to (URL), type in the URL to the Web server computer (for example, http://mycomputer).

  4. In the Add these project outputs box, clear the project. This prevents the project from automatically going in the Web Contents, Controls & Applets service node.

  5. Click OK.

  6. In the Deployment Explorer, expand the deployment target. For example, you would click on the box icon to the left of Deploy to http://mycomputer.

  7. Select the Server Components service node. On the Projects menu, click Add Project Outputs.

  8. In the Add Project Outputs dialog box, select the project and click OK.

  9. On the Project menu, click Deploy Solution.


Deploying Web Contents, Controls, and Applets

You can deploy your projects in two broad configurations — as server-side components run on the Web server, and as Web content files that are available for downloading from the Web server. The procedure in this topic shows you how to set up a deployment configuration for Web content, controls, and applets, and then deploy them.

Only projects that are generated by a build appear in the New Deployment Target dialog box.

To deploy Web components

  1. Open the project.

  2. On the Project menu, click New Deployment Target.

  3. In the New Deployment Target dialog box, click Deploy to (URL), type in the URL to the Web server computer (for example, http://mycomputer).

  4. In the Add these project outputs box, select the project. This automatically places the project in the Web Contents, Controls and Applets service node.

  5. Click OK.

If the Web project is a Microsoft® Visual InterDev™ project that also contains server-side components, the Microsoft development environment adds the project outputs to both services. If the server-side component is a Microsoft® Transaction Server (MTS) package, and the Web project is deployed, the server components also get added to the MTS package on the Web server.


Displaying the Deployment Explorer Window

You can use the Deployment Explorer window in the Microsoft development environment to view and manipulate deployment targets for the currently open solution.

The Deployment Explorer is automatically opened when you add a deployment target to your solution.

To display the Deployment Explorer window

  1. On the View menu, select Other Windows.

  2. Click Deployment Explorer.


Removing a Deployment Target from the Solution

In the Microsoft development environment, you can remove one or more deployment targets that describe your application configuration in its deployed state on the Web server.

To remove a deployment target from the solution

  1. In the Deployment Explorer window, select a deployment target.

  2. On the Project menu, click Remove.

  3. In the Remove Deployment Target dialog box, click Yes.


Removing Projects and Files from a Deployment Target

Deployment targets contain references to the projects and files that you want to be deployed. In the Deployment Explorer you can see the projects and files that will be deployed listed under each deployment target.

To remove a project or file from a deployment target

  1. In the Deployment Explorer, select the file or project that you want to remove.

  2. On the Project menu, click Remove.


Setting the Active (Default) Deployment Target

Your solution can contain any number of deployment targets. You can specify one of the deployment targets as the active (default) deployment target. Whenever you select Start from the Debug menu, or Deploy Solution from the Project menu, the Microsoft development environment automatically deploys the solution using the active deployment target. If the active deployment target is Deploy to My Computer, no deployment occurs after the project is built, and debugging takes place on the local computer.

The active deployment target is displayed in bold in the Deployment Explorer.

To set the active deployment target

  1. In the Deployment Explorer, select the deployment target that you want to set to active.

  2. On the Project menu, click Set as Active.

To turn off automatic deployment

  1. In the Deployment Explorer, select the Deploy to My Computer deployment target.

  2. On the Project menu, click Set as Active.


Solution Deployment User Interface Reference

You can deploy your Web application to a Web server for debugging and production in the Microsoft development environment. The following tool windows and dialog boxes assist in deployment tasks.

Add Project Outputs Dialog Box

Cannot Connect to Network Server Dialog Box

Deployment Explorer Window

Deployment Target (Deployment Target Settings Dialog Box)

File (Deployment Target Settings Dialog Box)

New Deployment Target Dialog Box

Server Component Installation (Deployment Target Settings Dialog Box)


Add Project Outputs Dialog Box

Use this dialog box to choose the projects that deploy to the current deployment target. Selecting a project specifies that the project's output files will be deployed to the deployment target URL. This dialog box displays all of the available and deployable projects in the current solution.

The project's output files are the files generated from a project's build process. You can also add files that you want included with a completed build as project output files.

For example, in a Microsoft® Visual J++™ project that implements an applet, the project output files would be the .class files, and any HTML files and resources that the applet requires. Similarly, the output file of a packaging project is the cabinet (.cab), Zip (.zip), or setup executable (.exe) that the packaging project builds.

Options

Add These Project Outputs

Adds the output files of the selected project to the deployment service (Server Components or Web Content, Controls, or Applets). The output files are generated after the project is built. In Visual J++, you will need to build the project to see the correct output file. Built output files (for example, Java .class files) are not generated until a build is finished successfully.

The project outputs displayed are all of the current possible project outputs from the solution.


Cannot Connect to Network Server Dialog Box

Use this dialog box to identify a problem that occurred while attempting to connect with the network server for deployment.

Options

One of the following errors may be displayed in the dialog box.

For More Information For step-by-step information on installing the Web Publishing API, see Configuring an IIS Server to Be a Deployment Target.

Cannot Ping Server

The Microsoft development environment is unable to verify contact with the requested network server. Either the target does not exist (or the URL was mistyped), or it is currently unreachable. Even if the server is unreachable, you can save the target information for use later. If you choose cancel, and you are creating a new target, you will be prompted to edit the target URL. If you choose cancel and you are modifying an existing target (using the Deployment Target Settings dialog box), the target information will revert to the previous version.

Try checking the spelling of the target machine, the status of the target machine, or try to connect to the target machine later, when the machine may be back online.

Web Publishing API Not Installed

The development environment cannot contact the requested network server because the Microsoft Web Publishing API is not installed on this machine.

Web Publishing API Version Outdated

The development environment cannot contact the requested network server because the network server's version of the Microsoft Web Publishing API is outdated.

Web Publishing API Copy Is Corrupted

The development environment cannot contact the requested network server because a component used by the Microsoft Web Publishing API (Piparse.dll) appears to be corrupted on the network server. Try reinstalling the Web Publishing API.

Installation of Web Publishing API Is Incomplete

The development environment cannot contact the requested network server because a component used by the Microsoft Web Publishing API (Piparse.dll) appears to be missing from the network server. Try reinstalling the Web Publishing API.

This Network Server Supports Component Installation

Enables the deployment of COM components and Java classes that run on the Web server. When the Web server is unreachable, the deployment target defaults to supporting only the deployment of client-side components. By selecting this option, you can override that default and specify that the Web server supports the deployment of server-side components.

To deploy server-side components from this service node, the target Web server must be configured with Microsoft Posting Acceptor 2.0 (or later versions). Without the proper configuration of the Web server, selecting this check box and deploying the deployment configuration will result in an error.

For More Information For step-by-step instructions on setting up your network server machine, see Configuring an IIS Server to Be a Deployment Target.


Deployment Explorer Window

The Deployment Explorer tool window displays the list of deployment targets in the current solution. The deployment target specifies the list of projects and files that are to be deployed, the URL to which files are deployed, and the configuration of components on the server.

Each deployment target can contain deployment services that the deployment target supports. There are two possible deployment services, as described in the following list.

  • Web Content, Controls, and Applets: for deploying components that run in the Web browser. These components include HTML pages, applets and other Java classes, and ActiveX® controls.

  • Server Components: For deploying components that run on the server. These components include Active Server Pages, Java classes and COM components.

Below each deployment service is the list of projects and files that are deployed to that service. The deployed configuration of the Web application is specified by appropriately distributing projects and files between the Web Content, Controls, and Applets service and the Server Components service.

You can:

  • View multiple services of different deployment targets at the same time.

  • Add new deployment targets.

  • Make a deployment target active by selecting it and clicking the Set as Active button.

  • Rename your deployment target by right-clicking on the selected item, selecting Rename from the context menu, and typing the new name.

  • Add project outputs and individual files to a deployment target.

  • Remove project outputs or individual files from a deployment target.

  • Remove deployment targets.

  • View settings for the Server Component Installation service node, individual files, and the Deployment Target itself. (You cannot view settings for Outputs, the Web Contents, Controls and Applets service node or the Deploy to My Computer target.)

  • You can expand and collapse the deployment target lists and view the services and items included in the services by clicking on the plus (+) or minus (-) to the left of the deployment target or service name.

  • Deploy the selected deployment target or the active deployment target.

  • Set a deployment target as the startup project for F5.

Elements

Prompts you for a new deployment target in the New Deployment Target dialog box.

Sets the selected deployment target as the active deployment target. This selected target is the default.

Removes the deployment target from the list in the Deployment Explorer. This removes the deployment target but does not delete the projects or files that it deploys.

Deploys the selected deployment target.

Displays the Deployment Target Settings for the Deployment Target, the Server Component Installation service node, or for individual files.

List Window

Lists all of the deployment targets and the corresponding services for each deployment target.

Deployment Target

Lists the names of the deployment targets in the current solution. By default, the deployment target name includes the target Web server's URL. You can add or remove deployment targets.

Double-click the service nodes in the Deployment Target node to expand or collapse the service nodes in the group.

Server Components Service

Lists projects and files that are deployed to the Web server. This service contains server-side components: Items deployed in this service are configured to run on the server. For example, ASP pages and COM server components are server-side components.

If your deployment target machine supports server-side components, this node will appear under that deployment target in the Deployment Explorer.

Web Content, Controls, and Applets Service

Lists projects and files that are deployed to the Web server. This service contains client-side components; items deployed in this service are configured on the server so that they can be downloaded and run on the browser. For example, HTML pages and ActiveX controls are client-side components.

Deploy to My Computer Target

This deployment target deploys the files locally to the developer's machine. This deployment target actually does not deploy any files, leaving them in locations where the development tools leave them. This is the default deployment target, and should be set as active whenever deployment to a remote server is not required.


Deployment Target (Deployment Target Settings Dialog Box)

Use this dialog box to change the deployment target URL, verify contact with (or "ping") the network server, and enable or disable automatic modification of HTML code within a deployed file to reference distribution units (cabinet or .zip files) created in the Microsoft development environment.

If you need to get new information on a network server, such as a newly installed server component capability, you can click OK on this dialog box, and the development environment will contact that server for fresh information on the server status and supported services. Click Cancel to exit this dialog box without contacting the network server.

Options

Deploy to (URL)

Changes the URL of the target Web server for the current deployment target. You can change the protocol to HTTP or HTTPS, depending on what your network server supports. You can enter or edit the URL for the network server.

For More Information For step-by-step instructions on setting up your network server, see Configuring an IIS Server to Be a Deployment Target.

Modify deployed Web pages so that applet and object tags reference deployed project outputs

Enables automatic modification of Web pages to reference distribution units (cabinet or .zip files) created in the development environment. This check box is selected by default, so that when a file containing HTML references is deployed, this feature will update any APPLET and OBJECT tags in HTML that reference components that are packaged into distribution units.

For More Information For more information on this link updating, see What is Deployment?.

You can disable this feature so that the HTML will not be modified when it is deployed, such as when you want to update the HTML code in your project by hand, or you are certain that your HTML code does not need updating.


File (Deployment Target Settings Dialog Box)

Use this dialog box to check the directory path of the file selected in the Deployment Explorer. This is useful if you are comparing two files with the same name but different locations.

Options

File Location

Displays the current full path of the file. This helps differentiate this file from another file with the same name and a different location. You cannot modify this path, but you can select and copy it.


New Deployment Target Dialog Box

Use this dialog box to specify the URL for a new deployment target and to add project output files to that deployment target. To add individual miscellaneous files to the deployment target, in the Deployment Explorer select the appropriate service within the target, right-click, then click Add Files.

A deployment target specifies the list of projects and files that are to be deployed, the URL to which files are deployed, and the configuration of components on the server. You can specify the URL of the new deployment target, and select any initial projects to be deployed as Web Content, Controls, or Applets.

Options

Deploy to (URL)

Enter the URL (Universal Resource Locator) of the target Web server. This can be in the format of HTTP (Hypertext Transfer Protocol) or HTTPS (Secure HTTP).

You can specify the root folder below which all components will be deployed. For example, you could type: http://servername/mysub, where "servername" would be the name of the machine, and "mysub" the name of the subdirectory or folder that you want to reach.

Add these Project Outputs

Adds the outputs of the selected project to the Web Contents, Controls, and Applets service by default. Selecting a project specifies that the project's output files are deployed to the target URL. The project's output files are the files that are generated from the build process or a file that you want included with a completed build.

For example, in a Visual J++ project that implements an applet, the output files would be the .class files and any HTML files and resources that the applet requires. Similarly, the output file of a packaging project is the .cab, .zip, or <setup>.exe file that the packaging project builds.


Server Component Installation (Deployment Target Settings Dialog Box)

Use this dialog box to change the default directory/folder for the deployment target, Server Component Installation service node. This is the location where all the server-side components are installed and registered on the network server machine when the project is deployed.

Note Microsoft® Visual InterDev™ projects are arranged hierarchically, which places the server-side components in many different folders when deployed. The Deploy to Folder feature in the Microsoft development environment places all the server-side components in one folder instead. If the server-side components are not in the same directory tree as the content (on the network server you deploy to), you can't get state information on the components for debugging.

Options

Deploy to Folder

This is the location on the network server machine where all the server-side components are installed and registered. You can change this folder from the default listed here. If necessary, a new folder will be created on the network server.

Note You are not notified if the component fails to register on the server.


Solution Deployment Error Messages

An unknown error occurred while attempting deployment

Are you sure you want to remove the deployment target <name>

Error accessing file: <name>

Error: Link fixup on file <name> failed.

Error: Microsoft Web Publishing API is corrupted (PIPARSE.DLL)

Error: Microsoft Web Publishing API is incomplete (missing PIPARSE.DLL)

Error: Microsoft Web Publishing API is not installed on this machine

Error: Microsoft Web Publishing API version is incorrect

Error: unable to retrieve the file <name> from the master network server

Error while checking status of projects used by target <name>

Failed to deploy a file <name>

Failed to deploy a file (<name>): Unknown server error

Failed to deploy the server components: <name>

Failed to deploy the server components: Unknown server error

Failed to generate installation file for <name>

Failed to generate output file list for <name>

Failed to generate server components file for <name>

Failed to generate Web page modification table

Invalid name. The name of a deployment target…

Network server returned invalid information…

The applet <name> is referenced in the file <name>, but the applet is not deployed in the current deployment target.

The file <name> already exists in service

The folder name is invalid. Please enter a valid target folder.

The object <name> is referenced in the file <name>, but the object is not deployed in the current deployment target.

The specified URL does not support deployment

The target name is invalid. Please enter a valid target URL.

There are one or more projects in the active deployment target…

Unable to add the files

Unable to contact the server <name>

Warning: Ambiguous object: The object <name> is generated by two or more projects

Warning: Invalid HTML <name>

Warning: <Name> exposes outputs which do not use Java Packages

Warning: The file <name> is written in a code page which is not installed on this machine.

Warning: The file <name> is in big-endian format.

Warning: The server component <name> was already deployed

Warning: The Web file <name> was already deployed from <name>


An unknown error occurred while attempting deployment

The development environment cannot successfully deploy the target.

Check your deployment settings and deploy again.


Are you sure you want to remove the deployment target <name>

The development environment is about to perform your request to remove a deployment target.

Once you confirm it, you cannot undo this action.


Error accessing file: <name>

The development environment could not copy a file for the deployment HTML tag update. The file may not exist or may have incorrect permissions.

Confirm that the file exists, and check the permissions set on the file.


Error: Link fixup on file <name> failed.

Deployment was aborted due to link fixup failure. Link fixup is the HTML tag reference update.

Check the HTML (or .asp or .alx) file to make sure the file isn’t corrupted, and try deploying again.


Error: Microsoft Web Publishing API is corrupted (PIPARSE.DLL)

The piparse.dll is corrupted on your computer.

Try reinstalling the Microsoft Web Publishing API on your computer.


Error: Microsoft Web Publishing API is incomplete (missing PIPARSE.DLL)

The piparse.dll is missing from your computer.

Try reinstalling the Microsoft Web Publishing API on your computer.


Error: Microsoft Web Publishing API is not installed on this machine

The piparse.dll was not installed on your computer.

Try reinstalling the Microsoft Web Publishing API on your computer.


Error: Microsoft Web Publishing API version is incorrect

An incorrect version of the Microsoft Web Publishing API was installed on your computer.

Try installing Web Publishing API version 1.53 or later from the Visual Studio CD or from the Visual J++ CD.


Error: unable to retrieve the file <name> from the master network server

The development environment cannot copy the Visual InterDev project you are deploying from the master copy.

Try the following:

  • Check the master copy on the server to see if it is corrupt, or if you have permissions to access the master. Deploy again.

  • Use the Get Local Copy command with the Visual InterDev project. Deploy again.


Error while checking status of projects used by target <name>

A Visual InterDev project is being checked to determine if it should be in both Web contents and Server components.

Remove the Visual InterDev project from the deployment target. Add the project again. Add it again if necessary.


Failed to deploy a file <name>

Web Publishing API sent an error.

Follow the Web Publishing API instructions.


Failed to deploy a file (<name>): Unknown server error

Web Publishing API sent an error.

Check your Web server for a proper installation and settings.


Failed to deploy the server components: <name>

Web Publishing API sent an error.

Follow the Web Publishing API instructions.


Failed to deploy the server components: Unknown server error

Web Publishing API sent an error.

Check your Web server for a proper installation and settings for server-side components.


Failed to generate installation file for <name>

The development environment cannot create a temporary file as part of the deployment process.

Confirm that you have disk space, an existing temporary directory, and permissions to read/write to that temporary directory.


Failed to generate output file list for <name>

The development environment cannot reconcile the list of files to the project outputs.

Rebuild your projects cleanly and deploy again.


Failed to generate server components file for <name>

The development environment cannot create a temporary cabinet file for deploying server components. Possible causes include: not enough disk space, .dll files are not registered, or a temporary directory doesn’t exist or has incorrect permissions.

Try the following:

  • Reinstall Visual Studio server components.

  • Rebuild projects with server components as outputs.

  • Check your temporary directory for space and read/write access.


Failed to generate Web page modification table

The development environment cannot find the project outputs or class files needed to perform an HTML link update.

Rebuild your project cleanly and deploy again.


Invalid name. The name of a deployment target...

The name provided for the deployment target contains only white space characters.

Rename your deployment target, such as “My Deployment Target”.


Network server returned invalid information...

The Web server software is corrupted or incorrect.

Reinstall PA Setup and IIS on your Web server. After you have set up the Web server, choose Settings on the deployment target, and click OK on the Settings dialog box. This will contact the server and update any new services available.


The applet <name> is referenced in the file <name>, but the applet is not deployed in the current deployment target.

The Microsoft development environment can only perform an update to the HTML tags APPLET or OBJECT tags if the object itself is also deployed.

Try the following:

  • Check the file and see if the HTML is correct.

  • Confirm that you are deploying the object or applet referenced in the HTML file.


The file <name> already exists in the service

The file being added already matches a file present in the deployment target service node.


The folder name is invalid. Please enter an valid target folder.

The folder name is invalid. Please enter a valid target folder.

The path supplied for the deployment target is not standard.

Confirm that there are no parentheses, wildcards, or other non-standard characters in the deployment target path. The path needs to be a full path, conforming to DOS path standards.


The object <name> is referenced in the file <name>, but the object is not deployed in the current deployment target.

The Microsoft development environment can only perform an update to the HTML tags APPLET or OBJECT tags if the object itself is also deployed.

Try the following:

  • Check the file and see if the file HTML is correct.

  • Confirm that you are deploying the object or applet referenced in the HTML file.


The specified URL does not support deployment

The URL for the deployment target has changed from a Web server to a computer without PA Setup or other Web server configurations.

The Server Components service information can be kept, but will not be used. You can add server components ability to a Web server by installing PASetup.exe.


The target name is invalid. Please enter a valid target URL.

The URL supplied is missing any key characters for the proper URL syntax. For example, a proper URL could read: HTTP://MyServer.

Enter a valid URL.


There are one or more projects in the active deployment target...

The Microsoft development environment no longer detects any server-side components in the deployment target, so the Server Components node has disappeared. The only remaining service node is the Web Content, Controls and Applets service node which contains client-side content.


Unable to add the files

You cannot add more than 1,000 files at once to the Deployment Explorer.

Try adding the files in batches of less than 1,000.


Unable to contact the server <name>

The Web server specified in the deployment target cannot be reached at this time. Possible causes include: network connections disrupted, loose cables, server moved, server name misspelled, proxy information incorrect, Web server turned off.


Warning: Ambiguous object: The object <name> is generated by two or more projects

Two projects create the same object or class. The development environment defaults to the first instance of the object or class.

Try changing the name of the project output in one of the projects.


Warning: Invalid HTML <name>

An OBJECT tag in HTML references a ZIP or a JAR.

Try referencing a ZIP or a JAR using the APPLET tag instead (used with the ARCHIVE statement).


Warning: <Name> exposes outputs which do not use Java Packages

Individual Java classes are included in a project without using Java Packaging.

Try placing your classes in Java Packaging.


Warning: The file <name> is written in a code page which is not installed on this machine.

The Microsoft development environment will not update the HTML references upon deployment. The file is in MBCS format in a code page which is not installed on the current computer.


Warning: The file <name> is in big-endian format.

The Microsoft development environment will not update the HTML references upon deployment. Even though the file is in Unicode or UTF-8, the file is the wrong endian format (big endian versus little endian).


Warning: The server component <name> was already deployed

Two or more projects generate the same component. The development environment defaults to the first instance.

Try changing the name of one of the components.


Warning: The Web file <name> was already deployed from <name>

A file specified as an output matches a file that was added to the deployment target. The development environment defaults to the first instance of the file.

Try changing the name of one of the instances of the file.


You are adding one or more projects which contain outputs...

The Visual InterDev project is added to the existing deployment target and needs reorganizing to fit the service nodes. The Web Content, Controls and Applets service node contains the client-side content, and the Server Components service node contains the server-side content.


Visual Component Manager Reference

Visual Component Manager is a tool for storing, organizing, and sharing reusable components. It can contain wizards, ActiveX® components, Database Connection objects, and many other components used in Microsoft® Visual Studio™ language projects. It can even contain entire Microsoft® Visual Basic and Microsoft® Visual J++™ projects!

The following sections provide information to acquaint you with Visual Component Manager concepts, procedures, and user interface.

Section | Description
Visual Component Manager Concepts | Provides an overview of Visual Component Manager and its features, as well as information about how to use it to manage large collections of shared components across multiple projects and development environments.
Visual Component Manager Common Tasks | Gives step by step instructions for using Visual Component Manager to publish, find, and reuse components, and on how to create repository databases both locally and on a network server for shared component management.
Visual Component Manager User Interface Reference | Describes Visual Component Manager's windows, dialog boxes, commands, and wizard.


Visual Component Manager Concepts

Component-based software development is the newest and most powerful way to build complex business applications. Instead of constantly reinventing the wheel, developers of component-based applications can simply "plug in" existing components that contain the needed functionality. When the right component doesn't already exist, it can be written once, and then cataloged for future reuse and sharing with other applications.

With Visual Component Manager you can publish components to a repository-based catalog, where they can easily be located, inspected, retrieved, and reused.

The following sections provide information to acquaint you with the important concepts of Visual Component Manager.

Section | Description
Publishing, Finding, and Reusing Components | Provides an overview of Visual Component Manager and its features, as well as detailed information on what you can accomplish with it.
Visual Component Manager Tool Window | Describes the Visual Component Manager Tool Window and acquaints you with its major features.
Repositories, Folders, and Items | Describes the three kinds of elements managed by Visual Component Manager, and explains how they are used to organize components for sharing and reuse.
Component Attributes | Lists the attributes that are assigned to components in Visual Component Manager. These attributes are used to determine how the components will be stored and reused, and to provide search criteria for locating the right component for the job.


Publishing, Finding, and Reusing Components

The biggest challenge of component-based development is managing all the separate components. Within a single application you may have hundreds or even thousands of separate components, and use each of these components in many different places in the program. What's more, you can reuse many components in other applications, saving enormous development time and effort — if you can locate the right component when you need it.

Visual Component Manager addresses the three main requirements for storing and organizing components: publishing, finding, and reusing them.

It provides a single source to organize, find, and insert components into your project. It can also be the centralized location for approved project programming conventions, functional specifications, and architectural models and diagrams.

Publishing Components

Publishing a component means storing it in a Visual Component Manager repository database, along with attributes and search keywords that will make it easy for others to find and reuse it.

When you publish a component, you add it to a Microsoft Repository database. This can be a local (Microsoft® Access) database on your own workstation, or it can be a shared Microsoft® SQL Server™ database on a network server. A shared database gives everyone who has access to that server the ability to find and reuse your component.

Visual Component Manager provides a single location for anything that can be added to a Microsoft® Visual Studio™ project. It allows you to catalog components, to find them easily using flexible search criteria, and to insert them into your project with point-and-click ease.

For example, you might create a template for a standard form used in all the accounting applications at the company, or a standard tax-calculation object that can be used in many applications. Cataloging these components on a shared repository database provides an easy way for all of the organization's developers to find and use the components. It also provides a convenient method of documenting their interfaces and usage requirements.

In addition to single components, Visual Component Manager can also store component libraries, templates, models, and complete application frameworks. For example, a tool developer might create a set of forms and basic modules that are the starting point for new forms and modules of the same type. By creating a template stored in Visual Component Manager, any developer can get a copy of the forms or modules and be able to add to or change it without affecting the original.

Because Visual Component Manager supports multiple databases, it is possible to selectively browse through items in a local repository database, switch to a departmental repository database (on a shared server), and then finally to enterprise scope on another shared database. In any repository database, you can use Visual Component Manager to drag items of interest into your local database, or insert them directly into your project.

For More Information To see step-by-step instructions for publishing components, see Publishing Components. For detailed information about the Microsoft Repository, search online in the MSDN Library Visual Studio 6.0 for "Repository Overview".

Finding Components

Visual Component Manager provides a flexible keyword and search mechanism to help organize and cross-reference components very flexibly. You can catalog and search for components by the component name, type, description, keywords, and annotations. With full text search capability, you can find components even if you don't know the exact component name.

Making best use of this search capability requires careful thought and consideration when you are publishing a component. You should be sure to enter the keywords most likely to describe the component to someone looking for it, or for someone searching for a component that has its functionality.

The keyword scheme also lets you group and categorize components hierarchically. For example, "Accounting" components might be further subdivided with keywords such as "Accounts Receivable" and "Payroll." By defining keywords to match both the larger category and the subcategories, a user can find either all items with the "Accounting" keyword, or just a subset with the "Payroll" keyword.

To provide good examples of well-indexed component entries, Visual Component Manager allows you to install entries for all controls, templates, forms, and other components supplied by Microsoft® Visual Basic®. You are given this option when you first run Visual Component Manager from within Visual Basic. Useful descriptions and keywords have already been entered, allowing you to find the component or tool you are looking for, and then launch or add it to your project with a click of the mouse.

For More Information For step-by-step instructions on finding components in a Visual Component Manager repository database, see Finding Components.

Reusing Components

Visual Component Manager lets you easily share and reuse code components, documentation, and other pieces of a project, as well as complete projects. When you locate a component you need, reusing it in your current project is usually as simple as clicking Add to my project on the component's shortcut menu. When reusing components that require Component Object Model (COM) registration, Visual Component Manager automatically registers the component for you when adding it to your project.

Programmers often create modules that contain "utility" functions that are used over and over again, to avoid reinventing the wheel. Storing such modules in Visual Component Manager provides an easy way to find and reuse such modules.

You can also associate additional files with components. A particular component may require the presence of additional support files such as .dll files, Help files, or documentation. With Visual Component Manager, you can associate multiple files with any component. This association becomes a part of the component item's properties in Visual Component Manager, and the associated files can be loaded along with the item.

When you use it in this way, Visual Component manager can also be the central location for approved project programming conventions, functional specifications, architectural models, and diagrams.

For More Information For step-by-step instructions on reusing components that have been published in Visual Component Manager, see Reusing Components in Your Project.


The Visual Component Manager Tool Window

Visual Component Manager provides a simple user interface to navigate through its contents, as well as a toolbar to quickly select the most common Visual Component Manager tasks. By default, it presents the three panes in the following list.

  • The explorer pane

  • The contents pane

  • The properties pane

These are shown in the following illustration.

You can hide the explorer and properties panes by clicking the toolbar buttons. The contents pane is always visible.

The explorer pane

The explorer pane shows a hierarchical view of the repository databases currently loaded into Visual Component Manager, along with the folders and subfolders within each. Clicking on the small plus (+) sign to the left of any repository or folders expands the view to show the folders it contains.

The contents pane

The contents pane displays the folders and items contained within the database or folder that is currently selected in the explorer pane. At the lowest level, the items displayed are components that have been published to Visual Component Manager.

The properties pane

The properties pane displays a list of all the properties and values assigned to the folder or item currently selected in the contents pane. At the component level, these properties include the component name, description, search keywords and other identifying information about the component. The properties pane also doubles as a browse pane to display object hierarchies for COM objects when you click Browse Details on the shortcut menu.

For More Information For more information about Repository databases, folders, and items, see Repositories, Folders, and Items. For more information about the properties Visual Component Manager assigns to the components it manages, see Component Attributes.


Repositories, Folders, and Items

The explorer pane displays a hierarchical folder view of Visual Component Manager's organization. This organization contains the three kinds of elements in the following list.

  • The top-level folders in this view are repository databases.

  • Each database contains subfolders.

  • Each subfolder can contain other folders and/or items.

Repositories

Visual Component Manager uses the Microsoft Repository to store and retrieve components. It can create and access two separate kinds of repository databases: Microsoft Access (.mdb) for local repositories and SQL Server for shared (team) repositories. When Visual Component Manager is first installed, it creates a Microsoft Access database on your local machine.

You can create or open additional repository databases of either type, using the Repository command in the shortcut menu.

Folders

Visual Component Manager organizes the components and other files it contains into folders. Each folder can contain both items (components and files) and subfolders. There are folders for each supported item type in the local repository database, and you can create additional folders by clicking New Folder on the shortcut menu.

Items

Individual components and other supported files are the lowest-level items stored in the repository database. In order to know how to load, reference, and otherwise manage the components it stores, Visual Component Manager categorizes each item by type. The item type determines the behind-the-scenes "handler" used by Visual Component Manager to perform various operations on the component item.

The types of items currently supported by Visual Component Manager include those listed in the following table.

Item types | File extensions
COM Server | .dll, .exe
COM Library | .dll
Standard Binaries | .dll, .exe
ActiveX® Control | .ocx
Active Document | .vbd
Visual Basic Project | .vbp
Visual Basic Project Group | .vbg
Visual Basic Sample Project | .vbp
Form Template | .frm
MDI Form Template | .frm
Class Template | .cls
Code Procedure Template | .bac
Control Set Template | .frm
Menu Template | .frm
Property Page Template | .pag
User Control Template | .ctl
User Document Template | .dob
Database Connection | .cls
Visual J++™ Project | .vjp
Java Class | .class
Java Applet | .java
HTML File | .htm, .html
Visual Model | .mdl
Documents/Misc. File | Any file name

For More Information For more information about the operations you can perform on repository databases, folders, and items, see Visual Component Manager Common Tasks. For a description of Visual Component Manager commands, see Visual Component Manager User Interface Reference.


Component Attributes

In order to help organize components so that you can easily locate and reuse them, Visual Component Manager maintains attribute information about each component stored in its repository database. These attributes are displayed in the properties pane of Visual Component Manager window.

Attribute | Description
Component Name | The name by which the component is recognized.
Type | The component type, as described in the topic Repositories, Folders, and Items.
Description | A brief description of the component's functionality, usage, interface(s) and any other useful information about the component.
Keywords | Words or phrases used to identify the component for searching.
File Name | The names of all files included with the component.
Author | The name of the component's author.
Date Published | Date the component was first added to Visual Component Manager.
Usage Count | Number of times the component has been reused from the current repository.
Has Source Code | True if source code is included, otherwise False.
Has Documentation | True if textual documentation is included, otherwise False.
Has Help File | True if online Help file(s) are included, otherwise False.
Has Sample Code | True if sample False.

Note that you enter most of these properties when you publish the component, by supplying information in the Publish Wizard. You can modify them by right-clicking the component in the contents pane and clicking Properties on the shortcut menu.

When you publish a component, you should be careful to enter complete and well-organized information in its attributes, since this information will be used by others to locate the components they need.

For More Information For more information about using component attributes to organize and search for published components, see Finding Components.


Visual Component Manager Common Tasks

This section contains step-by-step instructions for the most common Visual Component Manager tasks. These tasks include:

Finding Components

Installing and Starting Visual Component Manager

Publishing Components

Reusing Components in Your Project

Using Visual Component Manager with Visual Modeler

Working with Repository Databases


Finding Components

With Visual Component Manager you can use extensive search capabilities to help you locate the item you need.

To find an item in Visual Component Manager

  1. Click the Find button on the Visual Component Manager toolbar.

  2. In the Find Items in Visual Component Manager dialog box, click the Description tab.

  3. In the Named box, enter the name of the component you want to find. You can also use the * wildcard character to represent any string. For example, ACCT* will find all components with names that begin with ACCT

  4. In the Containing text box, enter one or more keywords or search strings.

    If more than one word is entered, Visual Component Manager finds all components containing one or more of the keywords. You can also place double quotation marks around one or more words to use the entire string as a search criterion. You can use the wildcard character * to represent any character string.

  5. In the Of Type list, specify the type of item you wish to search for.

  6. Select the appropriate check box to select the areas to searched for containing text: Keywords, Description, and/or Annotations.

  7. Click the History tab to narrow the search by specifying the author or person who last updated the component, publication dates, and use history.

  8. Click the Related Files tab to specify components that include sample code, source code, documentation, or Help files, as well as items with a specific name.

  9. Click Find Now to begin the search. All items in the repository database that meet the search criteria are listed in the dialog box’s Results pane. See Description Tab (Find Items in Visual Component Manager Dialog Box) for detailed information about each of the search options.


Installing and Starting Visual Component Manager

Visual Component Manager is automatically installed when you first install Visual Studio, Microsoft® Visual Basic, Microsoft® Visual J++™, Microsoft® Visual InterDev™, or Microsoft® Visual C++®. In Visual Basic, however, you must first add it to the toolbar in order to access it.

To add Visual Component Manager to the Visual Basic toolbar

  1. On the Visual Basic Add-ins menu, click Add-in Manager.

  2. In the add-ins list, scroll down and highlight Visual Component Manager.

  3. Under Load Behavior, select the Load on Startup check box.

  4. Click OK to add Visual Component Manager to the Visual Basic toolbar.

To start Visual Component Manager from Visual Basic

  • On the Visual Basic toolbar, click the Visual Component Manager icon.

    –or-

  • On the View menu, click Visual Component Manager.

To start Visual Component Manager from Visual J++ or Visual InterDev

  • On the Visual J++ or Visual InterDev toolbar, click the Visual Component Manager icon.

    –or-

  • On the View menu, click Visual Component Manager.

To start Visual Component Manager from Visual C++

  • On the Tools menu, click Visual Component Manager.


Publishing Components

You can use Visual Component Manager to publish reusable components on a shared repository database, where they can be located and used by other developers.

Visual Component Manager provides three ways to publish items to the repository database, as described in the following list.

  • Select a component in the Windows Explorer and drag it to a folder in the Visual Component Manager.

  • Select a project in your development environment and click Publish on the project's shortcut menu. When you click Source Files, you publish the project’s source code files; when you click Build Outputs, you compile and publish its outputs.

  • Click New on the Visual Component Manager shortcut menu.

Each of these methods opens the Publish Wizard, which walks you through a series of steps that allow you to publish a project for reuse.

For More Information For detailed instructions on publishing components using the Visual Component Manager Publish Wizard, see Visual Component Manager Publish Wizard.


Reusing Components in Your Project

The Visual Component Manager provides several ways to reuse files and components in your Visual Basic, Visual J++, or Visual InterDev project, depending on the type of item selected.

You can also reuse components, documents, specifications, and other items in VC++ or other programming environments, although you will not directly interact with these tools. In these cases, the components are copied from the Visual Component Manager database to your local hard disk, and Component Object Model (COM) components are registered in your system registry. You will have to add them to the VC++ or other language project in the ways typically available for those environments.

Some typical examples of reusing components are included in the following list.

To add a new project to your Visual Basic project group

  1. With Visual Basic running, locate and select the desired component item in the Visual Component Manager explorer or contents pane.

  2. On the shortcut menu, click Add to Project Group.

To add a new project to your Visual J++ or Visual InterDev solution

  1. With Visual J++ or Visual InterDev running, locate and select the desired component item in the Visual Component Manager explorer or contents pane.

  2. On the shortcut menu, click Install on this computer.

To add a new ActiveX® Control to your project

  1. With your development environment running, locate and select the desired component item in the Visual Component Manager explorer or contents pane.

  2. On the shortcut menu, click Add to Toolbox.

To add other COM objects to your project

  1. With your development environment running, locate and select the desired component item in the Visual Component Manager explorer or contents pane.

  2. On the shortcut menu, click Add to Project.

To add a new form to your Visual Basic project

  1. With Visual Basic running, locate and select the desired component item in the Visual Component Manager explorer or contents pane.

  2. On the shortcut menu, click Add to Project.

To use a published COM component in Visual C++ or other environments

  1. Locate and select the desired component item in the Visual Component Manager explorer or contents pane.

  2. On the shortcut menu, click Install on this computer.

To use other components in Visual C++ or other environments

  1. Locate and select the desired component item in the Visual Component Manager explorer or contents pane.

  2. On the shortcut menu, click Save to disk.

A shortcut method of adding most items to your project is to double-click on the item's icon in the Visual Component Manager contents pane.


Using Visual Component Manager with Visual Modeler

With Visual Component Manager, you can publish models created in Visual Modeler, and import and export these models to and from your Visual Basic project.

To import a class or logical package from the Visual Component Manager to a Visual Modeler model

  1. In Visual Modeler, open the model to which you want to import the class or package.

  2. In Microsoft Visual Basic, open the Microsoft Visual Component Manager as described in Installing and Starting Visual Component Manager, and click on the Visual Models folder. The published models are displayed in the contents pane.

  3. Select the model you want to import.

  4. On the shortcut menu, click Browse. A hierarchical list showing the logical packages, associations, and classes of the selected model is displayed in the properties pane.

  5. Expand the browser list to display the class or logical package you want to import.

  6. Drag the class or package from the list and drop it on an open class diagram or on a logical package in Visual Modeler.

Visual Modeler imports the selected class or logical package into the logical view of the current open model.

Publishing a Visual Modeler Model to the Microsoft Repository

To publish the entire logical view of the current open model to the Visual Component Manager

  1. Save the model.

  2. On the Tools menu, click Publish to VCM.

For more information about using Visual Component Manager with the Visual Modeler, search for Visual Component Manager in online Help for Visual Modeler.


Working with Visual Component Manager Repository Databases

A local repository database is created when you install Visual Component Manager. However, you may wish to create new special-purpose databases, or shared databases that allow you to publish your components and make them available to other developers on your network.

To create a new repository database

  1. Open the shortcut menu anywhere in the Visual Component Manager Explorer pane, point to Repository, and then click Create New.

  2. In the Select Database Type dialog box, click Microsoft Access Database (MDB) or SQL Server Database, and then click OK.

  3. Depending on which option you selected in the preceding step, do the following:
    • If you chose to create a Microsoft Access type database, the Create Access Type Database dialog box appears. Choose a Directory and File Name for the new database, and then click Save.

    • If you chose Microsoft® SQL Server™, the Select Data Source dialog box appears, prompting you to specify the DSN Name of the SQL Server database in which to create the new repository tables. Click OK.
  4. Visual Component Manager creates the necessary repository database tables and adds the new database to the Explorer pane.

To create a shared SQL Server database you must 1) have SQL Server installed on your computer, and 2) have an existing database in which to create the repository tables. If you want the database to be sharable, you must be logged in as System Administrator when you create the database. You can create a shared Access type database simply by creating it on a network server to which other developers have access.

To copy an item from one database to another

  1. Locate and select the item you want to add.

  2. Click it and drag it to the location you want to add it to.


Visual Component Manager User Interface Reference

This section includes reference information on items in the Visual Component Manager user interface. Click any of the links below for more information on the named item.

Add a Keyword Dialog Box

Add Annotation Dialog Box

Annotations Tab (Component Properties Dialog Box)

Description Tab (Component Properties Dialog Box)

Description Tab (Find Items in Visual Component Manager Dialog Box)

History Tab (Find Items in Visual Component Manager Dialog Box)

Item Keywords Dialog Box

Related Files Tab (Component Properties Dialog Box)

Related Files Tab (Find Items in Visual Component Manager Dialog Box)

Select Database Type Dialog Box

Visual Component Manager Main Screen

Visual Component Manager Publish Wizard


Add a Keyword Dialog Box

Use this dialog box to add to the current repository database new keywords for describing published components. Having a stored list of keywords helps to maintain search consistency and avoid duplication or misspelling of keywords.

This dialog is displayed when you click the plus (+) button on the Item Keywords Dialog Box.

Options

Enter New Keyword

Provides a place to enter a new keyword.


Add Annotation Dialog Box

Use this dialog box to enter textual annotations or comments to a component's properties. Annotations can be used for search criteria in the Description Tab of the Find Items in Visual Component Manager Dialog Box.

This dialog box is displayed when you click Add Annotation on the Annotations Tab of the Component Properties Dialog Box.

Options

Annotation by

Provides a place to enter the author of the annotation.

Annotation pane

Provides a place to enter the text of the annotation.


Annotations Tab (Component Properties Dialog Box)

Annotations Tab

Provides a place to display or add annotations (notes or comments) for the published component. Annotations can be used to provide tips, usage caveats, or any unstructured information about the component.

Add Annotation

Displays the Add Annotation dialog box, where you can add additional annotations to the item properties.


Description Tab (Component Properties Dialog Box)

Use this tab to view and enter description and keyword properties to identify an item.

Options

Description

Provides a place to display or enter a textual description of the component. The more detail you enter here, the better. A description of the component's suggested usage, interfaces, inputs and outputs, and similar information will help other developers reuse the component more easily.

Keywords

Provides a place to display and enter search keywords for the item. Keywords are a primary search mechanism in Visual Component Manager, so they should be chosen with care. Click Add to insert keywords from a list of available keywords that have previously been used in your database. If you need to insert new keywords, click the plus (+) sign in the Add a Keyword dialog box.


Description Tab (Find Items in Visual Component Manager Dialog Box)

Use this tab to enter descriptive criteria to search for a particular component or other item in Visual Component Manager.

Options

Named

Provides a place to enter a component name. You can use the * wildcard character to specify any string of 0 or more characters in the component name. For example, GRAPH* will find components named GRAPHICS.DLL, GRAPHDATA.OCX, GRAPH.EXE, and so on.

Containing text

Provides a place to enter one or more keywords or search strings. Click the ellipses (…) to display the Item Keywords dialog box, where you can select from the list of all keywords in your database. You can also use the * wildcard character to specify any string or any single character, respectively.

Of type

Lists types of items for which you can search.

Containing text in

Lists properties you can search for text. A check mark next to any of these properties means the search will return components for which that property contains the keyword or search string you entered in the Containing text box. The searchable properties are:

  • Keywords

  • Description

  • Annotations

Look In

Lists the available databases in which you can search.


History Tab (Find Items in Visual Component Manager Dialog Box)

Use this tab to indicate that you want to search for components based on a particular publication history or usage limits.

Options

All Components

Specifies, when selected, that you want the search to include all available components regardless of history.

Components

Enables, when selected, a list of history criteria by which you can search. You can select an item in the list to include only those components that meet particular history requirements.

Published or Updated by

Provides a place to enter the name of a particular person. Select Published or Updated from the list, then enter the name by which you want to search.

Between

Specifies, when selected, that you want to search for items published within a given date range. Enter those dates in the boxes provided.

In the last

Specifies, when selected, that you want to search for item published within the time you specify. Enter a number, and then specify days, months, or years in the list provided.

Has been used

Specifies, when selected, that you want to limit the search according to the number of times the component has been used since publication. Select greater than (>), less than (<), greater than or equal to (>=), or less than or equal to (<=), and then enter a number of times. Only those components that meet the specified usage history will be included in the search.


Item Keywords Dialog Box

Use this dialog box to pick from a list of currently available keywords when constructing a search string in the Find Items in Visual Component Manager dialog box, or when assigning keywords to a component from the Publish Wizard. You can also click the plus (+) sign to add new keywords to the list. See Finding Components for more information about keywords and searching.

Options

Add a New Keyword (+)

Displays the Add a Keyword dialog box, where you can add a new keyword to the repository database.

Available Keywords

Lists keywords currently available in the Visual Component Manager database.

List Keywords in

Lists the databases from which you can choose keywords.

Move All Keywords to the Right (>>)

Moves all keywords listed in the Available Keywords list to the Selected Keywords list.

Move All Keywords to the Left (<<)

Moves all keywords listed in the Selected Keywords list to the Available Keywords list.

Move the Selected Keyword to the Right (>)

Moves keywords selected in the Available Keywords list to the Selected Keywords list.

Move the Selected Keyword to the Left (<)

Moves keywords selected in the Selected Keywords list to the Available Keywords list.

Selected Keywords

Lists the keywords you have selected for this operation.


Related Files Tab (Component Properties Dialog Box)

Use this tab to display and enter related files that are published as part of the item.

Options

Component Contains

List the types of files that may be related to the selected component. Select the check box next to a file type to indicate that the item contains related files of that type. The listed file types include:

  • Sample Code.

  • Source Code.

  • Documentation.

  • Help Files.

An item named

Use this text box to enter the name of a particular file. The search results will include all components which contain that particular item as a related file.


Related Files Tab (Find Items in Visual Component Manager Dialog Box)

Use this tab to specify whether you want to search all components in the current database, or only components that contain particular related files.

You can search based on sample code, source code, documentation, or Help files, or any combination of these related files. You can also specify that you want to search only items that contain a specific related file.

Options

All Components

Specifies, when selected, that you want the search to include all available components, regardless of related files.

Components that include

Enables, when selected, a list of related file types by which you can narrow your search. Select the check box next to a related file type to include it in the search.

An item named

Provides a place to enter the name of a particular file. Only components that contain the file you enter will be included in the search.


Select Database Type Dialog Box

Use this dialog box to indicate which type of Visual Component Manager database you want to create or open. This dialog box appears when you point to Repository on a shortcut menu, and then click New or Open on the shortcut menu.

Options

Microsoft Access Database (MDB)

Specifies, when selected, that you want to create or open a Microsoft® Access type database.

SQL Server Database

Specifies, when selected, that you want to create or open a Microsoft® SQL Server™ database.


Select Folder Dialog Box

Use this dialog box to specify which folder you want Visual Component Manager to copy your component files to. This dialog box appears when you click Add to toolbox… on the shortcut menu.

Options

Path

Specifies the full directory path of the folder you want to add your component files to. The display is updated when you change the path by using the Folders and Drive options, described below.

When the drive and folder you wish to use appears correctly in the Path box, click OK to close the dialog box and add your components to the selected folder and the toolbox of your development environment.

Folders

Lists the folders on your current disk drive. Use the scrollbar to move up or down, and double click on a folder to select it. The selected folder appears in the Path text box. Click the New Folder button to add a new sub-folder to the current path.

Drives

Shows your current disk drive. Click the arrow to drop down the list box and show all disk drives on your machine, and network drives that have been mapped to a drive letter. Click another disk to choose folders from a different disk drive. Click the Network… button to select a network drive that has not yet been mapped to a drive letter on your local machine.


Visual Component Manager Main Screen

Use the main screen to select commonly used commands, and view the databases, folders, subfolders, and individual items stored by Visual Component Manager. These elements are briefly described below.

Options

Folders

Select from this list to set the focus of the explorer pane to a different database or folder.

Up One Level

Moves the focus up one level in the explorer pane.

Add a New Folder

Creates a new folder in the current database and inserts it into the explorer pane.

Publish a New Component

Starts the Visual Component Manager Publish Wizard to step you through publishing a new component.

Search

Opens the Find Items in Visual Component Manager dialog box, allowing you to search for items of any type. You can search by name, description, keywords, property values, or any combination of these.

Cut

Moves the current folder or item to the Clipboard.

Copy

Copies the current folder or item to the Clipboard.

Paste

Copies the group or item in the Clipboard to the selected folder.

Show/Hide Explorer Pane

Shows or hides the explorer pane in the Visual Component Manager user interface.

Show/Hide Properties Pane Button

Shows or hides the properties pane in the Visual Component Manager user interface.

Explorer

Hierarchically lists the databases, folders, and subfolders currently loaded.

Contents

Displays the items (components and other published files) in the currently selected folder of the repository database.

Properties

Displays the properties of the currently selected item. For COM components, the properties pane converts to a browse pane to display the object hierarchy when you select Browse from the shortcut menu.


Visual Component Manager Publish Wizard

The Visual Component Manager Publish Wizard takes you step by step through the process of publishing a component for reuse.

By filling in the requested information, you let Visual Component Manager know where and how to store the component, how to manage its interaction with the Visual Studio and other development environments, and how to identify it with keywords and search attributes so it can be easily located by other developers who wish to reuse it.

The wizard includes a standard set of buttons along the bottom. These buttons control the following actions.

Button | Description
Help | Displays Help for the Publish Wizard.
Cancel | Closes the wizard; nothing is published.
< Back | Moves back one step in the process.
Next > | Moves forward one step in the process.
Finish | Publishes the item and closes the wizard.

Select a Repository Folder

This step asks you to name the folder to which you want the item published, and to provide a name for the item. You may choose a folder on either a local or a shared repository database, or create a new folder. If you started the Publish Wizard from within Microsoft® Visual Basic®, Microsoft® Visual J++™, or Microsoft® Visual InterDev™, the name of the selected component is automatically filled in for you, but you can change it if you wish. If you started Publish Wizard from within a folder in Visual Component Manager, or by dragging an existing component into a Visual Component Manager folder, this step is skipped.

Title and Properties

This step asks you to identify the component so that it can easily be located, and so Visual Component Manager will know how to "handle" it when you want to reuse it in a project or solution.

Component Name

The name that will appear in the contents pane to identify the component.

Primary File Name

The name of the primary component file. For example, if you are publishing an ActiveX® control, the primary file name will be the .ocx file that encapsulates the control.

Type

Identifies the type of component you are publishing. This determines the handler assigned to the component for purposes of interacting with the tools environment and operating system, as well as providing a useful search criterion. For a list of supported component types, see Repositories, Folders, and Items.

Author

The person who wrote or republished the component being published.

The component includes

Select the check box next to each kind of additional support file you want to publish along with the component. The available options include:

  • Sample Code.

  • Source Code.

  • Documentation.

  • Help File.

More Properties

This step gives you the opportunity to add a verbal description and search keywords to the component you are publishing. A clear description and well-chosen keywords will make your component easier to find by others, and therefore more likely to be reused.

Description

A textual description of the component. The more detail you enter here, the better. A description of the component's suggested use, interfaces, inputs and outputs, and similar information will help other developers reuse the component more easily.

Keywords

Keywords are a primary search mechanism in Visual Component Manager, so they should be chosen with care. Click Add to insert keywords from a list of available keywords that have previously been used in your database. If you need to insert new keywords, click on the plus (+) sign in the Add a Keyword dialog box.

Select Additional File(s)

In this step you name all the files that will be published as a part of the component in addition to the primary file already listed. If the Publish Wizard has been launched from a project, the project files will be automatically included in the list, and you may add other files as well.

COM Registration

Specify which files, if any, Visual Component Manager must register for COM on the user's computer when this component is reused.

Once you click Finish, the wizard publishes the component to Visual Component Manager, and it appears in the folder you specified in step one.


Visual Component Manager Error Messages

This section contains reference information on Visual Component Manager error messages. These error messages include the following.

3001 - <Database> is already open

3003 - Cannot paste <folder>

3009 - <Component> must be saved before it can be published

3010 - <File> is already in the list

3012 - Unable to create TypeLibInfo from tlbinf32.dll

3014 - Unable to register <component>!

3015 - <Component> does not require Registration!

4042 - <Template> does not contain any Controls

4044 - <Menu template> does not contain any Menus

4049 - Template Failed to load correctly!

4064 - Unable to load the requested document

4078 - This operation can only be performed when a project is loaded

4079 - This operation can only be performed when a component is loaded

4081 - Current Component cannot accept Menus

4087 - Database cannot be loaded!

4094 - Can't Paste a Cut Folder onto itself!

4103 - <Component> already exists

4113 - Current Component cannot accept Controls

4124 - Item no longer exists in the gallery!

4125 - Error Extracting File

4130 - Project failed to build!

4135 - <Menu> could not be added

4138 - <Item> already exists as a folder

6025 - Can't Remove the Primary File


3001 - <Database> is already open

The Visual Component Manager database that you are attempting to open is already in use.

Try the following:

  • Check to see if you already have this database open.

  • If the database is not open, use the ODBC Data Source Administrator (in the Windows Control Panel) to view the DSN configuration for the database. If it is set for exclusive use only, turn the Exclusive flag off.


3003 - Cannot paste <folder>: The destination folder is a subfolder of the source folder

Moving a folder into one of its subfolders will lead to recursion, and is therefore prohibited.


3009 - <Component> must be saved before it can be published

You must first save a component before attempting to publish it into Visual Component Manager.


3010 - <File> is already in the list

You are attempting to add a file which is already listed as part of the component. You can publish a file into a given component only once.


3012 - Unable to create TypeLibInfo from tlbinf32.dll

The file you are publishing as a COM component does not contain a COM Type Library. While the component will still publish successfully, this will prevent browsing of the component once published.


3014 - Unable to register <component>!

Visual Component Manager encountered an error when attempting to register a COM component during a reuse operation such as "Add to Toolbox" or "Install on this Computer."

Try registering the component manually with Regsvr32.exe.


3015 - <Component> does not require Registration!

You marked a file as requiring COM registration, but the component does not support COM registration. This can only be verified automatically on in-process components such as .dll and .ocx files.


4042 - <Template> does not contain any Controls.

A Visual Basic Control Set Template you are attempting to reuse does not contain any controls.

Try saving the control set to disk first, rather than reusing it directly from within Visual Component Manager.


4044 - <Menu template> does not contain any Menus

A Visual Basic Menu Template you are attempting to reuse does not contain any menus.

Try saving the menu template to disk, rather than reusing it directly from within Visual Component Manager.


4049 - Template Failed to load correctly!

Visual Component Manager was unable to reuse a previously published Visual Basic template.

Try saving the template to disk first rather than reusing it directly from within Visual Component Manager.


4064 - Unable to load the requested document

Visual Component Manager failed when it attempted to open a previously published document.

Try saving the document to disk first, rather than opening it directly from within Visual Component Manager.


4078 - This operation can only be performed when a project is loaded

You are attempting to add a component to a project when no project is open or selected.

Select a currently open project, or open one if no project is already open, then add the component.


4079 - This operation can only be performed when a component is loaded

You are attempting to add a previously published Visual Basic template to a project when no Visual Basic component is selected.

Before attempting to reuse the template, select a Visual Basic component in the Visual Basic Project Explorer.


4081 - Current Component cannot accept Menus

You are attempting to reuse a Visual Basic menu template into a Visual Basic component that cannot accept Menus.

Select a Visual Basic Component that can host a menu, such as a Form.


4087 - Database cannot be loaded!

Visual Component Manager was unable to open the database.

To correct the problem, try the following:

  • Check to see if you already have this database open.

  • If the database is not open, use the ODBC Data Source Administrator (in the Windows Control Panel) to view the DSN configuration for the database. If it is set for exclusive use only, turn the Exclusive flag off.


4094 - Can't Paste a Cut Folder onto itself!

You cannot paste a folder into itself.


4103 - <Component> already exists

You have attempted an operation, such as Paste, where a component of the same name already exists in the target folder.

Rename the existing component before pasting the new one into the same folder.


4113 - Current Component cannot accept Controls

This message appears when you try to reuse a Visual Basic Control Set Template into a Visual Basic component that cannot accept controls.

Select a Visual Basic Component that can host controls, such as a Form.


4124 - Item no longer exists in the gallery!

This error occurs if another user, attached to the same Visual Component Manager Database, has deleted the component you are clicking.

Try refreshing the folder's content. Right-click the Folder, then click Refresh from the folder's shortcut menu.


4125 - Error Extracting File

Visual Component Manager is unable to extract the previously published component from the database.

Try the following:

  • Click Save to disk… on the shortcut menu to save the component to a folder on your hard disk, rather than reusing it directly from within Visual Component Manager. You can then add the component to your project in the usual way.

  • Detach from the database, reattach, and then try to perform the reuse action again.


4130 - Project failed to build!

You are trying to publish the build outputs of a project that cannot successfully build.

Try fixing the bugs that are stopping the build from succeeding, and then publishing again after the build succeeds.


4135 - <Menu> could not be added

Visual Component Manager failed to add a menu to a Visual Basic Component from a previously published Visual Basic Menu Template.

Click Save to disk… on the shortcut menu to save the menu template to a folder on your hard disk, rather than reusing it directly from within Visual Component Manager. You can then add it to your Visual Basic project as you would any other template.


4138 - <Item> already exists as a folder

You tried to change the name of a component to the same name as a subfolder in the current folder.

Rename the subfolder before renaming the component.


6025 - Can't Remove the Primary File

You tried to remove the primary file from a component's file list when publishing the component. You can't remove the file that was specified as the primary file in Step One of the Publish Wizard.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.