Programming with the Microsoft.HtmlTrans.Interface Namespace

  • Article

A user may view a document from a document library without having an application capable of displaying the requested document installed on the client computer. Microsoft Windows SharePoint Services provides the Microsoft.HtmlTrans.Interface namespace as an infrastructure on which to build custom converter applications that deliver an HTML version of the requested document to the user in these circumstances in place of the unrecognized binary file format.

Caution  The HTML Viewer feature must be enabled in SharePoint Central Administration in order to use this functionality.

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 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 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>

Warning  Changes that you make to htmltransinfo.xml may be lost when you update Windows SharePoint Services such as through service packs or patches.

Using the Microsoft.HtmlTrans.Interface Namespace

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

  • 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.
  • 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 so, Windows SharePoint Services delivers the document in its native format.
  • 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 designated by the ProgId. If this attempt fails, Windows SharePoint Services continues with the HTML conversion process.
  • 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.
  • If the user chooses to convert the document, Windows SharePoint Services forwards the request to the handler page 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 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 at all.
  • Call the custom implementations of the IHtmlTrLoadBalancer and IHtmlTrLauncher interfaces provided as part of the Microsoft Office 2003 Editions Resource Kit and provide a custom converter application for the IHtmlTrLauncher implementation to call.