Understanding DocIcon.xml Files

Applies to: SharePoint Foundation 2010

A file named DocIcon.xml is present on every front-end web server in a Microsoft SharePoint Foundation deployment. Its purpose is to provide a way to specify the icon that is displayed for any given file type that might be uploaded to a list or document library and, optionally, to specify whether an ActiveX control should be used to open the file.

Functions of DocIcon.xml

Each front-end web server in a SharePoint Foundation deployment has a DocIcon.xml file located on the following path:

%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\XML\DocIcon.xml

The purpose of this file is to associate file types with the following:

• The document icon that represents a file type in lists and search results.

• (Optional) The ActiveX control that opens a file of this type for viewing or editing.

• (Optional) The text that appears in drop-down menus as the editing item ("Edit in Application Name") for a file that is uploaded to a list.

The settings in DocIcon.xml are global to a SharePoint Foundation deployment and affect all site definitions on all front-end web servers. Each file name extension or ProgId can map to only one editing control, one icon, and one string of display text. This mapping is the same throughout a SharePoint Foundation deployment. You can add mapping elements to support additional file name extensions and ProgIds.

Warning

If you modify DocIcon.xml, you must make identical changes on each front-end web server so that all servers remain in sync. A good way to do this would be to distribute changes to DocIcon.xml as part of a farm-level Feature. In addition, you should be aware that changes that you make to DocIcon.xml may be overwritten when you install updates or service packs to SharePoint Foundation, or when you upgrade an installation to the next product version.

File Format

For detailed information about the schema for DocIcon.xml, see Document Icons Schema. In general, the schema provides two ways that mapping can be performed: by file name extension (for example, "docx") and by ProgId (for example, "Word.Document").

Note

A ProgId is a registry entry that associates the programmatic identifier (ProgID) of a COM object with its class identifier (CLSID). For example, the registry key HKLM\Software\Classes\Word.Document has a subkey named CLSID with a value of {F4754C9B-64F5-4B40-8AF4-679732AC0607}. In this case, the key name Word.Document is a ProgId. Because the key has a subkey with a CLSID value, you can use Word.Document as a shorthand way of saying {F4754C9B-64F5-4B40-8AF4-679732AC0607}. For more information, see <ProgId> Key (COM).

The ByProgID element contains a series of Mapping elements that map the program identifiers of different file types to file icons, specifies the text that is displayed for each file type in the drop-down menu that appears when the Edit arrow is clicked, and specifies the ProgId of the control to use for opening documents of a given type. The following example shows part of a ByProgID section:

<DocIcons>
  <ByProgID>
    <Mapping
      Key="Excel.Sheet" 
      Value="ichtmxls.gif" 
      EditText="Microsoft Office Excel" 
      OpenControl="SharePoint.OpenDocuments" />
    <Mapping 
      Key="FrontPage.Editor.Document" 
      Value="ichtmfp.gif" 
      EditText="Microsoft Office FrontPage" 
      OpenControl="SharePoint.OpenDocuments" />
    ...
  </ByProgID>

The image that is referenced in the Value attribute must be stored in the IMAGES folder of each front-end server on the following path:

%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\IMAGES

The control that is referenced by the OpenControl attribute must be deployed on each client that accesses the SharePoint Foundation environment.

The ByExtension element maps file name extensions to file icons, specifies the text to display for each file name extension in the drop-down menu that appears when the Edit arrow is clicked, and specifies the ProgId of the control to use for opening documents with a given file name extension. The following example shows part of a ByExtension section:

  <ByExtension>
    <Mapping
      Key="asax" 
      Value="icasax.gif" />
    <Mapping 
      Key="ascx" 
      Value="icascx.gif" />
    <Mapping 
      Key="asmx" 
      Value="icasmx.gif" />
    ...
    <Mapping 
      Key="mpp" 
      Value="icmpp.gif" 
      EditText="Microsoft Office Project" 
      OpenControl="SharePoint.OpenDocuments" /> 
    <Mapping 
      Key="mps" 
      Value="icmps.gif" /> 
    <Mapping 
      Key="mpt" 
      Value="icmpt.gif" 
      EditText="Microsoft Office Project" 
      OpenControl="SharePoint.OpenDocuments" />
    ...
  </ByExtension>

The Default element specifies the default image file to be used for file types that are not specified in DocIcon.xml, as seen in the following example.

  <Default>
    <Mapping Value="icgen.gif" />
  </Default>
</DocIcon

Note

To resolve conflicts, ByProgID takes precedence over ByExtension. However, document templates that are specified in the Onet.xml file of a site definition work only in relation to file types that are specified within the ByExtension element.

See Also

Concepts

Document Icons Schema

How to: Add a Document Template, File Type, and Editing Application to a Site Definition