Building MSXML Applications

This topic introduces the issues that you need to address when building your MSXML applications.

Overview

There are a variety of ways that you can use MSXML to build applications that process XML:

• You can process XML as part of a web application, displaying the results in an internet browser such as Internet Explorer. You can either use the MIME viewer or a scripting language.

• You can use the Document Object Model (DOM) using a scripting language as a stand-alone process.

• You can use the DOM or Simple API to XML (SAX2) using C++ language. You can also use either API in any language or development system that can consume ActiveX controls or COM objects.

Customer feedback has indicated that it is often difficult for developers to build and run MSXML applications. Sometimes developers find they are using a different version of the library than they expected. Sometimes it is difficult simply to get their application to run. There are a number of issues that you need to take into consideration when building your application. This topic lists the issues and provides guidance.

About the Examples

Most of the examples that the MSXML SDK provides work as delivered with either MSXML 6.0 or MSXML 3.0. This topic provides instructions on making MSXML 3.0 samples work with MSXML 6.0. Some of the MSXML 3.0 examples will not work with MSXML 6.0 for some reasons, including:

• Examples written in MSXML 3.0 that use Document Type Definitions (DTDs) will not work with MSXML 6.0 without modifications, as MSXML 6.0 disables DTDs by default.

• Examples written in MSXML 3.0 that use XML Data Reduction (XDR) schemas will not work with MSXML 6.0. XDR schema functionality has been removed from MSXML 6.0.

Examples that use MSXML 3.0 in a web application using the MIME viewer work as delivered, provided that they are running on a computer that has been updated with the latest patches.

Explanation of CLASS_IDs, GUIDs, and ProgIds

When you create a COM or ActiveX object such as MSXML, you must identify exactly which control you want to create. In the case of MSXML, which has multiple versions, you must create the instance of your control in such a way that you get the correct version of the control that you need. First, you need to know some basic information about how ActiveX controls and COM objects work.

An ActiveX control is definitively identified by a GUID, which is a very large unique number that is assigned to the control. It is most often expressed as a hexadecimal number. An example of a GUID is 88d96a05-f192-11d4-a65f-0040963251e5. Sometimes the GUID is referred to as the ClassID of the control. However, it is inconvenient to use the GUID to identify and create the control. Instead, there are two other ways to refer to an ActiveX control:

• When you are using a scripting language, you can identify the control via its ProgID, which is a form that is quite a bit easier to read by a human. An example of a ProgID is Msxml2.DOMDocument.6.0.

• When you are using C++, you can create the control via its symbolic name. This is a name that is defined as a macro in a header file. An example of a symbolic name is CLSID_DOMDocument60. If you use that symbolic name in your C++ program, it resolves to the GUID of the control.

When you install an ActiveX or COM control, Windows Registry entries are created that identify the correspondence between a GUID, a ProgID, and the location of the component.

If you are using a scripting language such as JScript or VBScript, when you create your control, the scripting engine will take the ProgID that you specify, look up the GUID in the registry, and create the correct control using its GUID.

For more details, see GUID and ProgID Information.

Explanation of ProgID Naming

ProgIDs, which you use to instantiate an ActiveX control when using a scripting language, are typically made up of a project name followed by a class name, in the form of ProjectName.ClassName. The following is a list of ProgIDs for the DOMDocument for various versions of MSXML that are supported for public use as of November, 2005:

Notice the project name portion of the ProgID. For versions of MSXML from version 3.0 through version 6.0, the project name portion is Msxml2. ProgIDs use Msxml2 for legacy reasons - there are a number of technical reasons, none of which matter much in this context, and which are beyond the scope of this document. The main point is to realize that when you are using a ProgID of Msxml2.DOMDocument.6.0, just because it has Msxml2 in the name doesn't mean that you are using version 2 of MSXML; you are really using version 6.

There are two ProgIDs that you can use with MSXML 3.0: Msxml2.DOMDocument or Msxml2.DOMDocument.3.0. See GUID and ProgID Information for more information.

This has in the past been a point of confusion for developers. However, it is really simple - when you want to use a particular version of the library, use the tables (found at GUID and ProgID Information) to determine the correct ProgID.

Attempting to Run an Example for a Version of MSXML that Is Not Installed

The most common error, and one of the more frustrating experiences for new MSXML programmers, is attempting to run an XML application (typically written using a scripting language) that uses a version of MSXML that has not been installed on their computer. When you do this, you get an error, "Automation server can't create object".

When you get this error, you need to do one of two things - either you need to install the targeted version of MSXML, or you need to modify your script to use a ProgID for a version of MSXML that you have installed on your system. For more information see, Installing and Redistributing MSXML.

This is probably a less common error for C++ developers than for script programmers. C++ developers know that to build their application, they need access to the MSXML header file, and they need to link with the appropriate library. The MSXML header file and library are installed when installing the MSXML SDK, so if they are able to compile and link, they have installed the correct version of MSXML.

C++ developers, of course, need to make sure that if they are distributing their application that they install the correct version of MSXML on their target machines. Failure to do so will result in an error when they attempt to run their EXE: "This application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem." Reinstalling the application will not fix the problem; installing the correct version of MSXML will, though.

Using XML in Internet Explorer

There are a number of ways that you can use XML in a Web application using Internet Explorer:

• You can view the XML in IE. An easy way to do this is to browse to the directory that contains your XML file and double click on the file. This will display the XML file in a hierarchical form. When you use this method in Internet Explorer 7 or earlier version, you are using MSXML 3.0, so features such as XSD schema validation are not available.

• If you write an XSLT stylesheet and reference the stylesheet in your XML file, you can open the XML file with IE7 or earlier version and see the transformed document rendered as HTML. When you use this method, you are using MSXML 3.0; so again, features such as XSD schema validation are not available. See Hello, World! (XSLT) for an example of doing this.

• You can initiate XSLT in a script. When you use XSLT in this fashion, you have the option of specifying a version dependent ProgID, so you are able to specify exactly which version of MSXML you want to use. Further, with this approach, you have the option of using advanced features such as XSD schemas and the schema cache. When you are using this method, remember to replace the ProgID with the version specific ProgID that corresponds to the version of MSXML that you want to use. See Initiate XSLT in a Script for this type of example.

• A more sophisticated example of initiating XSLT in a script, as well as examples of using XPath, can be found at XPath Tutorial Application.

Building Applications Using JScript

It often is convenient to run stand-alone scripts written in either JScript or VBScript. This is convenient when you are learning XML. It also is useful to do this when you are using some of the XML tools such as XSLT to transform XML documents from one form to another; one example of doing this might be where you need to manipulate and transform data after exporting the data from one database, and before importing it into another. If this is a one-off operation, you may not want to automate the process. Instead, you may want to simply execute a JScript program that uses the DOM to do the transform.

Before running your JScript application, make sure that you have modified it so that you are creating an ActiveX object for the version of MSXML that you want. Your application would typically create the DOMDocument object as follows:

var doc = new ActiveXObject("msxml2.DOMDocument.6.0");  

See GUID and ProgID Information to determine the correct ProgID.

See Program with DOM in JScript for details on programming the DOM using JScript.

Using the DOM, you can develop applications that do XSLT transformations using JScript. You can also write applications that use XMLHTTP and ServerXMLHTTP.

You can't develop SAX2 applications using scripting languages such as JScript and VBScript. You can only do so using C++, and other development environments that support consumption of COM objects.

Building Applications Using VBScript

Running stand-alone scripts using VBScript is similar to running stand-alone scripts using JScript. The reasons why you would want to do so are the same for the two scripting languages.

Similar to using JScript, before running your VBScript application, make sure that you have modified it so that you are creating an ActiveX object for the version of MSXML that you want. Your application would typically create the DOMDocument object like this:

Set xmlDoc = CreateObject
("Msxml2.DOMDocument.3.0")  

See GUID and ProgID Information to determine the correct ProgID.

An example that shows programming MSXML with VBScript can be found at Validate XML to a DTD (VBScript). This example has been validated with MSXML versions 3.0, and MSXML 6.0.

Building Applications Using C++

When using MSXML with C++, you need to a number of things to build and run your application. They include:

• Configuring the directories for include files - you need to add an entry for the inc directory in the MSXML SDK.

• Configuring the directories for lib files - you need to add an entry for the lib directory in the MSXML SDK.

• In the properties for the project, specifying the MSXML library that you need to link into your application.

• Modifying the source for the example or application to include the appropriate MSMXL header file.

• Modifying the source for the example or application to use the correct ClassID for the version of MSXML that you are using.

• Making sure that the MSXML dynamic link library (DLL) is in your path. Typically, MSXML3.dll, MSXML4.dll, MSXML5.dll, and MSXML6.dll are put into the WINDOWS\system32 directory.

The following table lists the versions of MSXML, the header name, the library name, and the DLL name.

You need to include the header file and link with the library according to the above table.

What is more important is that you need to set your directories appropriately in Visual Studio so that the compiler finds the header file for your desired version of MSXML, and that the linker links with the right library.

Most of the C++ examples include msxml2.h. If you want to build your example to use MSXML 6.0, you will need to change the header file and library, per the above table.

See Also

MSXML SDK Overview