Programming with the Microsoft.HtmlTrans Namespace

Applies to: SharePoint Foundation 2010

Users can view documents from a document library even if they do not have an application installed on the client computer that can display the requested documents. Microsoft SharePoint Foundation 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.

Warning

To use this functionality, you must enable the HTML Viewer feature in SharePoint Foundation Central.

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

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

  • The IHtmlTrLauncher interface starts the custom converter application and returns the HTML results to SharePoint Foundation.

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

Warning

Changes that you make to the htmltransinfo.xml file may be lost when you update SharePoint Foundation with a service pack or security update.

Using the Microsoft.HtmlTrans Namespace

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

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

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

  3. SharePoint Foundation 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, SharePoint Foundation continues with the HTML conversion process.

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

  5. If the user chooses to convert the document, SharePoint Foundation 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 SharePoint Foundation platform you must create the following:

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

  • A handler page that starts 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 SharePoint Foundation.

  • 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 SharePoint Foundation Object Model

Other Resources

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