HowTo: Insert an image into a Word document and display it using OpenXML

Steve Morgan — Mon, 15 Sep 2008 11:01:00 GMT

One of the tasks I've had over the last few weeks has been to automatically generate documentation from an architectural model. It's been (and continues to be) a relatively painful, sluggish process, as I'm generating Microsoft Word 2007 documents using the Open XML SDK. Never more so than when I came to add support for including images.

I'm going to do a 10,000' pass through the way that I approached it, so it's not a beginners guide to OpenXML. You're going to need to be able to find your way around an OpenXML document using the Open XML SDK first.

The basic process I'm using is to generate from my architectural model an XML document that will ultimately become a Microsoft Word document, like this:

<?xml version="1.0" encoding="utf-8" ?>
<content xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
  <bookmark id="ContentToReplace">
    <para style="Heading1">Major Heading</para>
    <para style="Heading2">Secondary Heading</para>
    <table>
      <tr>
        <td>
          <para>Name</para>
        </td>
        <td>
          <para>Steve Morgan</para>
        </td>
      </tr>
      <tr>
        <td>
          <para>Address</para>
        </td>
        <td>
          <para>www.hastobe.net</para>
          <para>Somewhere in Hyperspace</para>
        </td>
      </tr>
    </table>
    <para style="Heading2">Another Secondary Heading</para>
    <image src="..\..\testfiles\mypic.png"/>
    <para>Good now, sit down, and tell me, he that knows,</para>
    <para>Why this same strict and most observant watch</para>
    <para>So nightly toils the subject of the land,</para>
    <para>And why such daily cast of brazen cannon,</para>
    <para>And foreign mart for implements of war;</para>
    <para>Why such impress of shipwrights, whose sore task</para>
    <para>Does not divide the Sunday from the week;</para>
    <para>What might be toward, that this sweaty haste</para>
    <para>Doth make the night joint-labourer with the day:</para>
    <para>Who is't that can inform me?</para>
  </bookmark>
</content>

I have some code that rips through a Word template document, looking for bookmarks and replacing the content of those bookmarks with Open XML fragments. The fragments themselves are derived from the above XML structure using nothing more than good old-fashioned XSLT.

Generating paragraphs of text and tables is pretty simple, as other than transforming the XML and inserting the resulting Open XML into the document, there's not much to it.

Images, on the other hand, are a little more complicated. There are two stages to adding an image to a Word document (or any Open XML document, for that matter). The first is that you must add an "Image Part" that holds the binary representation of the image, itself. Finding out how to do that was pretty easy:

WordProcessingDocument m_Document = ...the document you're building...
 
public void InsertImage(string imageFile, string contentType)
{
    ImagePart part = m_Document.MainDocumentPart.AddImagePart(contentType);
 
    using (FileStream stream = new FileStream(imageFile, FileMode.Open))
    {
        part.FeedData(stream);
    }
}

This function adds a new image part to the document and copies the content of the image file. However, getting the image displayed on the page is another matter entirely. It should be no surprise that we must add some markup to the main document to render the image. I created what I consider to be a minimal Open XML fragment that creates a single paragraph containing nothing but the requested image:

<w:p xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
    xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/
               wordprocessingDrawing"
    xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" 
    xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture"
    xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
  <w:r>
    <w:drawing>
      <wp:inline>
        <wp:extent cx="{WIDTH-IN-EMUS}" cy="{HEIGHT-IN-EMUS}" />
        <wp:docPr id="{DRAWING-OBJECT-ID}" name="{FILENAME-OF-IMAGE}" 
                  descr="An automatically inserted image" />
        <wp:cNvGraphicFramePr>
          <a:graphicFrameLocks noChangeAspect="1" />
        </wp:cNvGraphicFramePr>
        <a:graphic>
          <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/
                                2006/picture">
            <pic:pic>
              <pic:nvPicPr>
                <pic:cNvPr id="{PICTURE-ID}" name="{FILENAME-OF-IMAGE}" />
                <pic:cNvPicPr />
              </pic:nvPicPr>
              <pic:blipFill>
                <a:blip r:embed="{RELATIONSHIP-ID-OF-IMAGE-PART}" cstate="print"/>
                <a:stretch>
                  <a:fillRect />
                </a:stretch>
              </pic:blipFill>
              <pic:spPr>
                <a:xfrm>
                  <a:off x="0" y="0" />
                  <a:ext cx="{WIDTH-IN-EMUS}" cy="{HEIGHT-IN-EMUS}" />
                </a:xfrm>
                <a:prstGeom prst="rect"/>
              </pic:spPr>
            </pic:pic>
          </a:graphicData>
        </a:graphic>
      </wp:inline>
    </w:drawing>
  </w:r>
</w:p>

Now, do you see those upper-case names in parenthesis (such as {WIDTH-IN-EMUS})? They're placeholders for values that must be dynamically inserted and are derived as follows:

{WIDTH-IN-EMUS}

That's the width of the image. Not measured in terms of flightless birds, but English Metric Units. There are 914400 EMUs to the inch, so it's calculated from:

widthInEmus = widthInPixels / HorizontalResolutionInDPI * 914400;

{HEIGHT-IN-EMUS}

Similarly, this is the height of the image in English Metric Units. Calculated from:

heightInEmus = heightInPixels / VerticalResolutionInDPI * 914400;

{DRAWING-OBJECT-ID}

This is a unique identifier for the Drawing Object. I calculate the initial value by looping through all of the existing <wp:docPr> elements in the document to find the largest Id, then increment it for each new image.

{FILENAME-OF-IMAGE}

Just for the sake of convention, I put the terminal name of the image file in here.

{PICTURE-ID}

This is a unique identifier for the Picture (as opposed to the Drawing Object - hmm?) and is derived in the same way as {DRAWING-OBJECT-ID} but from <pic:cNvPr> elements, not <wp:docPr>.

{RELATIONSHIP-ID-OF-IMAGE-PART}

This is what binds the image placeholder in the document to the image resource that we've embedded in the new Image Part. To get it, we need to change our InsertImage function slightly:

public string InsertImage(string imageFile, string contentType)
{
    ImagePart part = m_Document.MainDocumentPart.AddImagePart(contentType);
 
    using (FileStream stream = new FileStream(imageFile, FileMode.Open))
    {
        part.FeedData(stream);
    }
    
    return m_Document.MainDocumentPart.GetIdOfPart(part);
}

The value returned by InsertImage is the Relationship Id that we insert into this attribute in the XML.

So there you have it (for now). Equipped with your new Image Part and appropriate Open XML fragment, you should now to able to insert images, ad-nauseum, into your Open XML documents. I apologise for having skimmed over the subject at such a high level. Hopefully, I'll get round to posting some more articles on Open XML that will fill in a few of the blanks. In the meantime, if you need some specific help, let me know.

Steve Morgan - Technology Spot : OpenXML, Imaging

HowTo: Insert an image into a Word document and display it using OpenXML