How to Package Components for Internet Distribution

Article
08/15/2017

Application packaging is the process of creating a container that can install your application on a user's computer. This tutorial explains how to create Internet Component Download packages, called distribution units. When placed on a Web server and referenced from a Web page, distribution units enable users to download and install software from Web sites on the Internet and intranets.

The example in this tutorial takes you through the steps necessary to add a toolbar button to the default user interface in Microsoft Internet Explorer 5 and later. A toolbar button can run a Microsoft Win32 application, run a script, or open an Explorer Bar.

For more information about browser extensions, which enable developers to add elements to the default user interface in Windows Internet Explorer, see About Browser Extensions.

Like many of the applications you will distribute, the toolbar button demonstration requires making registry entries and installing files on the user's computer. The steps in this tutorial are not specific to adding toolbar buttons. They can be applied to most Web-bound software distributions.

Requirements and Dependencies
Implementation Steps
- Step 1: Create the Software
- Step 2: Prepare for Internet Distribution
- Step 3: Create the INF File
- Step 4: Create the Open Software Description (OSD) File
- Step 5: Compress the Files in a Cabinet File
- Step 6: Offer the Software to Users
Final Wrap-up
Related topics

Requirements and Dependencies

Developers who want to create Internet software distribution units should be familiar with the registry and GUIDs.

Internet Component Download is supported by Internet Explorer version 3.0 or later. INF files are also supported by Microsoft Internet Explorer 3.0 and later. Open Software Description (OSD) files are supported by Microsoft Internet Explorer 4.0 and later. And toolbar buttons can be added to the user interface in Internet Explorer 5 and later.

Toolbar buttons also require two .ico files: one with the active (color) icons and one with the default (grayscale) icons. For more information about what icons are required, and for tips on designing icons for Internet Explorer, see Toolbar Button Style Guide.

Implementation Steps

In this section you will learn, step-by-step, how to package components for Internet Distribution.

The toolbar button you'll create in the demonstration exercise will run a script that navigates to the MSDN Library. Of course, you can create a button that navigates to your own home page.

Step 1: Create the Software

For the toolbar button, create an .htm file containing the following script, and save the file as "navigateMSDNLibrary.htm." This is the script that Internet Explorer will run when the user presses the toolbar button. Save navigateMSDNLibrary.htm in an empty folder called "ButtonDownload."

<SCRIPT LANGUAGE=JAVASCRIPT DEFER>
external.menuArguments.document.location.href=
    "https://msdn.microsoft.com/library/"

</SCRIPT>

Name the two .ico files "ColorButton.ico" and "GrayButton.ico" respectively. Place the .ico files in the ButtonDownload folder also. This folder will contain all of the files you will create and use in this exercise.

Create a valid GUID.

Detailed instructions for adding toolbar buttons to the default user interface in Internet Explorer 5 and later can be found in Adding Toolbar Buttons.

Step 2: Prepare for Internet Distribution

Ask questions like the following when preparing software for Internet distribution. The answers to these questions will determine the method you'll use to package the software.

What files do you need to distribute?
Is it necessary to make any registry entries on the user's computer?
Should the files be installed in specific folders on the user's computer?
Are any of your components dependent upon other components?
What is the earliest version of Internet Explorer you wish to support?

For a thorough discussion of packaging method criteria, see Choosing a Packaging and Distribution Method.

Let's address all of these questions for the toolbar example. In this instance, the two .ico files must be distributed, as well as the .htm file that contains the navigation script. Several registry entries are needed. INF files should be installed in the user's \Windows\Inf folder. The .ico and .htm files don't have to be installed in specific locations, as long as you can specify the locations of the files in the registry—that is, you must know where you're putting them. And toolbar buttons can only be added to Internet Explorer 5 and later.

Registry entries require INF files. You can also use your INF file to create a new folder on the user's computer, and to install files in the new folder.

The distribution unit in this instance will consist of a single cabinet file that contains the .ico and .htm files, and an INF file. The cabinet file will also contain an Open Software Description (OSD) file that specifies international language, operating system, and processor dependencies for the distribution.

Step 3: Create the INF File

An INF file provides installation instructions that Internet Explorer (version 3.0 and later) uses to install and register software components downloaded from the Internet, as well as any files required by the components. The INF file is a text file that specifies the files that need to be present or downloaded for your component to run. INF files provide a way to register downloadable components and can handle limited software dependencies.

For more information about INF files, see Using INF Files.

The [version] section of the INF file

The first section of the INF file is the [version] section. In the sample INF file, this section has the following format.

;INF version.
[version]
signature="$CHICAGO$"
AdvancedINF=2.0

The signature tag specifies that the INF version is compatible with Windows 95 or later, Microsoft Windows NT 4.0, and Windows 2000 and later. The AdvancedINF tag identifies the version of Advpack.dll that Internet Explorer must load in order to parse this INF file. In this case, version 2.0 is required.

The Install Section of the INF File

Install sections identify the additional sections in the INF file that contain installation information for the component. Naming the install section [DefaultInstall] will cause the install section to be executed when Install is selected from the INF file's context menu (right-clicking the INF file displays the context menu). The following example of a typical install section contains CopyFiles and AddReg items that identify sections containing information about which files to install.

;installation information sections
[DefaultInstall]
CopyFiles=InstallFilesSection,InstallInfSection
AddReg=AddRegSection

The AddReg section of the INF file

The AddReg section is used for adding subkeys or value names to the registry and for setting values. The name of the AddReg section must appear in an AddReg item in an install section such as [DefaultInstall].

The syntax for the AddReg section is as follows:

reg-root-string,(subkey),(value-name),(flag),(value)

The following sample of an AddReg section was excerpted from the INF file for the toolbar button demonstration:

;registry entries to be made on the user's machine
[AddRegSection]
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","Default Visible",,"Yes"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}",
    "CLSID",,"{1FBA04EE-3024-11D2-8F1F-0000F87ABD16}"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","ButtonText",,"MSDN Library"

HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","HotIcon",,
    "C:\DownloadDemo\ColorButton.ico"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","Icon",,
    "C:\DownloadDemo\GrayButton.ico"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","Script",,
    "C:\DownloadDemo\navigateMSDNLibrary.htm"

Notice that all of the registry entries will be made in HKEY_LOCAL_MACHINE (HKLM). Using the GUID you created in Step 1, a new subkey is created in the registry under "Software\Microsoft\Internet Explorer\Extensions." Value names and their respective values are added to the registry under the new subkey. Because there are no entries with flags, the spaces for these entries are delimited by commas.

The CopyFiles section of the INF file

The CopyFiles section contains a list of the files to be copied to the user's computer. The source location for the files and the destination directory associated with each file are specified in other sections of the INF file. The name of the file-list section must appear in the CopyFiles item of an install section.

The following example details the CopyFiles sections of the INF file for the toolbar button download, as well as the sections of the INF file that specify the locations of the source files and their respective destination directories.

;files to be copied to the user's machine
[InstallFilesSection]
ColorButtonIcon=ColorButton.ico
GrayButtonIcon=GrayButton.ico
ScriptFile=navigateMSDNLibrary.htm


[InstallInfSection]
InfFile=ButtonDownload.inf

[ColorButtonIcon]
file-win32-x86=thiscab
FileVersion=1,0,0,0

;source location for specified platform version
[GrayButtonIcon]
file-win32-x86=thiscab
FileVersion=1,0,0,0

;source location for specified platform version
[ScriptFile]
file-win32-x86=thiscab
FileVersion=1,0,0,0

;source location for specified platform version
[InfFile]
INFFile=ButtonDownload.inf
file-win32-x86=thiscab
FileVersion=1,0,0,0

;destination directory for files in the CopyFiles section
[DestinationDirs]
InstallFilesSection=30,DownloadDemo ;new folder in boot drive
InstallInfSection=17                ;Windows\Inf folder

Notice that the INF file will be installed in the \Windows\Inf folder (17), and that the other files will be installed in a new folder called DownloadDemo, which will be created in the root directory of the user's boot drive (30). The files are all located in the same cabinet file as the INF file (thiscab).

The Sample INF file

Copy the following text file, and save it in your ButtonDownload folder as "ButtonDownload.inf."

[version]
signature="$CHICAGO$"
AdvancedINF=2.0

;installation information sections
[DefaultInstall]
CopyFiles=InstallFilesSection,InstallInfSection
AddReg=AddRegSection

;registry entries to be made on the user's machine
[AddRegSection]
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","Default Visible",,"Yes"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}",
    "CLSID",,"{1FBA04EE-3024-11D2-8F1F-0000F87ABD16}"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","ButtonText",,"MSDN Library"

HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","HotIcon",,
    "C:\DownloadDemo\ColorButton.ico"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","Icon",,
    "C:\DownloadDemo\GrayButton.ico"
HKLM,"Software\Microsoft\<tla rid="tla_ie" />\Extensions\
    {A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}","Script",,
    "C:\DownloadDemo\navigateMSDNLibrary.htm"


;files to be copied to the user's machine
[InstallFilesSection]
ColorButtonIcon=ColorButton.ico
GrayButtonIcon=GrayButton.ico
ScriptFile=navigateMSDNLibrary.htm


[InstallInfSection]
InfFile=ButtonDownload.inf

[ColorButtonIcon]
file-win32-x86=thiscab
FileVersion=1,0,0,0

;source location for specified platform version
[GrayButtonIcon]
file-win32-x86=thiscab
FileVersion=1,0,0,0

;source location for specified platform version
[ScriptFile]
file-win32-x86=thiscab
FileVersion=1,0,0,0

;source location for specified platform version
[InfFile]
INFFile=ButtonDownload.inf
file-win32-x86=thiscab
FileVersion=1,0,0,0

;destination directory for files in the CopyFiles section
[DestinationDirs]
InstallFilesSection=30,DownloadDemo ;new folder in boot drive
InstallInfSection=17                ;Windows\Inf folder

Note The sample INF file above demonstrates the syntax for Win32 INF files. INF files for Internet Component Download generally include [Add.Code] and [Setup Hooks] sections. If both of these sections are missing, as in the example above, Internet Explorer assumes that the INF file is a Win32 INF file, and the system processes the INF file's [Default Install] section. About INF File Architecture contains additional information about the syntax, structure, and processing of INF files.

Step 4: Create the Open Software Description (OSD) File

OSD is an XML vocabulary. OSD files use text markup to describe software components and their relationships to other components. The OSD vocabulary is a standard (open) way to describe software components, their versions, their underlying structures and their dependence on other components.

OSD files can describe complex software, language, and platform dependencies. This functionality ensures that only the components actually needed by the user's computer will be downloaded.

The sample INF file in the previous section does not include installation instructions for computers running Microsoft Windows NT 4.0, Windows 2000, or any other platform. An OSD file will be used to specify the operating system and hardware configuration required by the toolbar button distribution.

For more information about OSD files, see Introduction to Open Software Description.

XML version identification and document type definitions

All OSD files have the same basic foundation. OSD files begin with the XML version identification and the Document Type Definition (DTD) file. Next create the XML namespace msicd, which enables you to use the elements defined in the Microsoft Internet Component Download DTD file.

<?xml version="1.0"?>
<!DOCTYPE SOFTPKG SYSTEM
  "https://msdn.microsoft.com/standards/osd/osd.dtd" >

<?XML::NAMESPACE
  HREF="https://msdn.microsoft.com/standards/osd/msicd.dtd"
  AS="msicd"?>

The SOFTPKG element

The main section of an OSD file begins and ends with the SOFTPKG element, which defines the software distribution. The SOFTPKG attribute of the SOFTPKG element contains the name of the software distribution and is required. The SOFTPKG attribute corresponds to the major, minor, custom, and build version numbers. Nested within the SOFTPKG element in the sample OSD file are TITLE and ABSTRACT elements, which name and summarize the software distribution.

<SOFTPKG NAME="{A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}"
  VERSION="1,0,0,0">
    <TITLE>Toolbar Button Download</TITLE>
    <ABSTRACT>
      The toolbar button navigates to the MSDN Library.

    </ABSTRACT>
    .
    .
    .
</SOFTPKG>

The NATIVECODE section

The next section of the sample OSD file is also nested within the parent SOFTPKG element. The NATIVECODE element specifies one or more native code distributions. OSD files can also be used to describe JAVA applications.

The CODE element is used to describe a specific instance of native code. In this instance, the CODE attribute of the CODE element contains the GUID for the toolbar button distribution, and the CODE attribute of the CODE element points to the ButtonDownload.inf file.

The IMPLEMENTATION element is used to describe what type of hardware your code requires. In the sample OSD file, note that the IMPLEMENTATION element is nested inside the CODE element. The CODE element is nested inside the NATIVECODE element, which is nested inside the SOFTPKG element.

Nested within the IMPLEMENTATION element of the sample OSD file are CODEBASE, LANGUAGE, OS, and PROCESSOR elements. The CODEBASE element specifies the location of the file or distribution unit to be installed. In this instance, the CODEBASE attribute of the CODEBASE element refers to an INF file that is located in the same cabinet file as the OSD file. The LANGUAGE element specifies which languages the software's user interface supports, which is English ("en") in this instance. The OS element specifies the operating system the software supports, which is "Win95" in this instance. And the PROCESSOR element specifies the type of processor the software will run on, which is "x86" in this instance.

    <MSICD::NATIVECODE>
        <CODE CLASSID="{A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}"
          NAME="ButtonDownload.inf"
          VERSION="1,0,0,0">
            <IMPLEMENTATION>
                <CODEBASE FILENAME="ButtonDownload.inf" />
                <LANGUAGE VALUE="en" />
                <OS VALUE="Win95" />
                <PROCESSOR VALUE="x86" />
            </IMPLEMENTATION>
        </CODE>
    </MSICD::NATIVECODE>

The Sample OSD File

Copy the following text file, and save it in your ButtonDownload folder as "ButtonDownload.osd."

<?xml version="1.0"?>
<!DOCTYPE SOFTPKG SYSTEM
  "https://msdn.microsoft.com/standards/osd/osd.dtd" >

<?XML::NAMESPACE
  HREF="https://msdn.microsoft.com/standards/osd/msicd.dtd"
  AS="msicd"?>

<SOFTPKG NAME="{A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}"
  VERSION="1,0,0,0">
    <TITLE>Toolbar Button Download</TITLE>
    <ABSTRACT>
      The toolbar button navigates to the MSDN Library.

    </ABSTRACT>

    <MSICD::NATIVECODE>
        <CODE CLASSID="{A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6}"
          NAME="ButtonDownload.inf"
          VERSION="1,0,0,0">
            <IMPLEMENTATION>
                <CODEBASE FILENAME="ButtonDownload.inf" />
                <LANGUAGE VALUE="en" />
                <OS VALUE="Win95" />
                <PROCESSOR VALUE="x86" />
            </IMPLEMENTATION>
        </CODE>
    </MSICD::NATIVECODE>

</SOFTPKG>

Note Syntax is very important in OSD files. XML files, in general, have very strict syntax requirements. Be careful to copy the sample OSD file precisely. If your distribution units don't download and install correctly, check the syntax of your OSD file first. (Check the syntax of your INF file second).

Step 5: Compress the Files in a Cabinet File

Cabinet files (.cab) are used to reduce file size and therefore the associated download time. The cabinet file format provides an efficient way to package multiple files, compressing the data in the files across file boundaries to improve the compression ratio. Microsoft supplies a Cabinet Software Development Kit containing tools a developer can use to build cabinet files.

Cabarc is a command line utility included in the Cabinet Software Development Kit. It is used to create, extract, and list the contents of cabinet files. When you download the Cabinet software development kit (SDK), place Cabarc.exe in the same path as the files to be included in the cabinet file.

To create a new cabinet file using Cabarc, issue the following command from a ButtonDownload prompt:

cabarc n ButtonDownload.cab ColorButton.ico GrayButton.ico
navigateMSDNLibrary.htm ButtonDownload.inf ButtonDownload.osd

This command will create a cabinet file called ButtonDownload.cab that contains the ColorButton.ico and GrayButton.ico files, the navigateMSDNLibrary.htm file, and the ButtonDownload.inf file. The n option specifies that this is a new cabinet file. (Cabarc no longer requires the -s 6144 option to reserve 6144 bytes in the cabinet file for a digital signature.) You can use the l option to list the contents of your newly created cabinet file, as follows:

cabarc l ButtonDownload.cab

For detailed instructions on using Cabarc, see the Cabarc User's Guide included in the Docs folder of the Cabinet SDK.

Sign the cabinet file

The cabinet file should be digitally signed. Digital signatures associate a software vendor's name with a given file, providing accountability for software vendors. A certificate authenticates a signed file. It notifies users that a specific software program is genuine, ensuring that no other program can assume the identity of the original program.

When a user's security level is set at the default level, any object identified by the OBJECT tag on a Web page must be digitally signed. The Internet Explorer default security setting won't install a component that doesn't have a digital signature.

Microsoft Authenticode technology is a set of developer tools for signing cabinet files and programs, and for checking that files and controls were successfully signed. You can download the Authenticode toolset from MSDN Online.

Authenticode technology has been available since Internet Explorer 3.0. When Internet Explorer 4.0 was released, there was a corresponding upgrade for Authenticode. When Internet Explorer 5 was released, the MakeCat program was added to the Authenticode toolset. The MakeCat program can be used by developers with Internet Explorer 5 and later. To avoid errors resulting from the use of mismatched versions of Authenticode, be sure to download the version of Authenticode that corresponds to your version of Internet Explorer:

Windows Server SDK (Internet Explorer 4.0 and later)
Windows Software Development Kit (Windows Internet Explorer 7)

Download the appropriate version of the Authenticode tools. Unzip the files to your ButtonDownload directory. The steps for applying a test signature to the demonstration cabinet file using Authenticode technology for Internet Explorer 4.0 and later are as follows:

Generate a test certificate using the MakeCert test program.

The following command typed at the ButtonDownload prompt will create a self-signed certificate named myNewRoot using the default test root:
```
MakeCert -sk myNewRootKey -r -ss myNewRoot
```
Sign the cabinet file using the SignCode program.

Use the SignCode program with the certificate you created above to sign the ButtonDownload.cab cabinet file. The cabinet file will be signed, but not time stamped.
```
SignCode -s myNewRoot ButtonDownload.cab
```
Check the validity of the cabinet file with the ChkTrust program.

Issue the following command from the ButtonDownload prompt to check the validity of the ButtonDownload.cab cabinet file using the ChkTrust program:
```
ChkTrust ButtonDownload.cab
```

Detailed instructions for using the Authenticode tools can be found in Signing and Checking Code with Authenticode.

Step 6: Offer the Software to Users

Reference your software distribution package from a page on your Web site.

Components are usually addressed by the CODEBASE attribute of an object tag on a Web page.

<OBJECT CODEBASE="http://.../ButtonDownload.cab#version=1,0,0,0"
    CLASSID="clsid:A6B13EE4-A974-11d2-8DB7-00C04FB6E8F6">

Note When distributing portable executable image files—such as .dll, .exe, and .ocx files—it is important for the #version fragment of the CODEBASE attribute to match the version information specified in the distribution unit.

Final Wrap-up

MSDN Online provides developer tools that are useful for testing your distribution units. Members can download these tools free of charge. The Microsoft Code Download Log Viewer is a tool for troubleshooting code download failures.

By default, custom toolbar buttons do not appear on the Internet Explorer toolbar. These buttons will appear on the left side of the Customize Toolbar dialog box. After downloading the new toolbar button you created, however, users can simply close and reopen the Internet Explorer window to view their new toolbar. When they reopen Internet Explorer, the new toolbar button will be visible. This is because you set "Default Visible" to "Yes" in the registry you made with your INF file.

Conceptual

About Browser Extensions

Internet Component Download

Microsoft Internet Component Download Reference

Open Software Description Element Reference

Adding Toolbar Buttons

Packaging ActiveX Controls