Programming with the Microsoft.HtmlTrans Namespace

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

A user can view a document from a document library even if they do not have an application installed on the client computer that is capable of displaying the requested document. Windows SharePoint Services provides the Microsoft.HtmlTrans namespace as an infrastructure on which to build custom converter applications that deliver an HTML version of the requested document in place of the unrecognized binary file format.

The Microsoft.HtmlTrans.Interface namespace consists of two interfaces, IHtmlTrLoadBalancer and IHtmlTrLauncher. An implementation of these interfaces also relies on an XML configuration file, called htmltransinfo.xml, which resides on the server that is running Windows SharePoint Services.

• The IHtmlTrLoadBalancer interface helps to select the server on which to run the custom converter application.

• The IHtmlTrLauncher interface launches the custom converter application and returns the HTML results to Windows SharePoint Services.

• The htmltransinfo.xml file redirects the document request to a handler page, which then calls the load balancer and launcher components. An entry in the htmltransinfo.xml configuration file uses the following format:

  <HtmlTrInfo>
      <Mapping Extension="ext" AcceptHeader="application/vnd.my-app" HandlerUrl="myapphandler.aspx" ProgId=""/>
  </HtmlTrInfo>
  

Using the Microsoft.HtmlTrans Namespace

The following sequence of events occurs when a user requests a document from a server that is running Windows SharePoint Services:

1. Windows SharePoint Services identifies the file extension of the document in the htmltransinfo.xml file. If found, Windows SharePoint Services retrieves the matching AcceptHeader attribute; if not found, Windows SharePoint Services prompts the user to download the document.

2. Windows SharePoint Services checks the AcceptHeader attribute value against the Accept-Header HTTP header of the request to see whether the client computer recognizes the requested document type. If it does, Windows SharePoint Services delivers the document in its native format.

3. Windows SharePoint Services also retrieves the ProgId attribute from the Htmltransinfo.xml file and attempts to open the file on the client computer by using the component that is designated by the ProgId. If this attempt fails, Windows SharePoint Services continues with the HTML conversion process.

4. If the client computer does not recognize the requested document type, Windows SharePoint Services prompts the user: "Do you want to convert the document for viewing in the browser?" If the user chooses not to convert the document, Windows SharePoint Services prompts the user to download the document instead.

5. If the user chooses to convert the document, Windows SharePoint Services forwards the request to the handler page that is specified by the HandlerUrl attribute in the Htmltransinfo.xml file. The handler page manages the conversion process and delivers the converted file to the user for viewing in the browser.

Implementing Custom Document Conversion

To implement custom document conversion on the Windows SharePoint Services platform you must create the following:

• An entry in the Htmltransinfo.xml file for the document type.

• A handler page that launches the document conversion process and returns the HTML output to the user.

• A set of custom conversion components.

You must choose among three methods to build the set of custom conversion components:

• Build custom implementations of the IHtmlTrLoadBalancer and IHtmlTrLauncher interfaces that can be used to launch a custom converter application and return its results to Windows SharePoint Services.

• Build a set of custom conversion components that do not use the Microsoft.HtmlTrans interfaces.

• Call the custom implementations of the IHtmlTrLoadBalancer and IHtmlTrLauncher interfaces that are provided as part of the Microsoft Office 2003 Editions Resource Kit and provide a custom converter application for the IHtmlTrLauncher implementation to call.

See Also

Concepts

Namespaces in the Windows SharePoint Services Object Model

Getting Started with Programmatically Customizing a SharePoint Web Site in Visual Studio