C# Document Element Tutorial
IronWord is a powerful Word document library designed to assist .NET C# developers in integrating the capabilities of creating, reading, and editing Word and DOCX documents into their applications. In the context of a Word document, document elements are the building blocks that make up the content.
Quickstart: Create a Styled TextRun and Embed an ImageHere's how you can use IronWord to add rich content - combining styled text and an embedded image in a document. This example demonstrates the Run wrapper pattern for styled text.
-
1Install IronWord with NuGet Package Manager
-
2Copy and run this code snippet.
using IronWord; using IronWord.Models; // Create document WordDocument doc = new WordDocument(); // Create styled Run Run textRun = new Run(new TextContent("Hello IronWord!")); textRun.Style = new TextStyle() { IsBold = true, Color = Color.Blue }; // Create paragraph and add Run Paragraph paragraph = new Paragraph(); paragraph.AddChild(textRun); paragraph.AddImage(new ImageContent("pic.png")); // Add to document and save doc.AddParagraph(paragraph); doc.SaveAs("output.docx");C# -
3Deploy to test on your live environment
Start using IronWord in your project today with a free trial
Table of Contents
- Add Text
- Text Content (Add, Append & Split)
- Set Styling (Font Family & Size, Color, Bold & Italic, Strikethrough, Underline, Superscript & Subscript)
- Embed Images
- Add Images
- Load Image (File & FileStream)
- Set Wrap Text
- Set Dimensions (Width & Height)
- Set Position Offset
- Set Distance from Corners
Key Concepts
Document Hierarchy
IronWord follows a structured document hierarchy: Document → Paragraph → Run → TextContent. Understanding this hierarchy is essential for working with styled text:
WordDocument: The top-level container representing the entire documentParagraph: A block of content within the documentRun: A wrapper object that containsTextContentand can have styling appliedTextContent: The actual text string
Adding Content to Paragraphs
IronWord provides two methods for adding content to paragraphs:
AddText(TextContent): Use for unstyled plain text. AddsTextContentdirectly to the paragraph.AddChild(Run): Use for styled text. Adds aRunobject (which wrapsTextContentand holds styling) to the paragraph.
When you need to apply styling like font size, color, or bold formatting, create a Run object, assign a TextStyle to the Run, and use AddChild to add it to the paragraph.
Add TextRuns
Text Content
The Split method is utilized to divide the text run into a list of smaller text runs, based on a specified delimiter. This allows for the organization and manipulation of textual information within the document.
using IronWord;
using IronWord.Models;
WordDocument doc = new WordDocument();
// Add text
TextContent addText = new TextContent("Add text using IronWord");
doc.AddParagraph(new Paragraph(addText));
// Append text
TextContent appendText = new TextContent("The first text.");
appendText.Append(new TextContent("The second text."));
doc.AddParagraph(new Paragraph(appendText));
// Split text
TextContent splitText = new TextContent("Use split to split the sentence.");
splitText.Split(" ");
doc.AddParagraph(new Paragraph(splitText));
// Export docx
doc.SaveAs("textrun.docx");Imports IronWord
Imports IronWord.Models
Private doc As New WordDocument()
' Add text
Private addText As New TextContent("Add text using IronWord")
doc.AddParagraph(New Paragraph(addText))
' Append text
Dim appendText As New TextContent("The first text.")
appendText.Append(New TextContent("The second text."))
doc.AddParagraph(New Paragraph(appendText))
' Split text
Dim splitText As New TextContent("Use split to split the sentence.")
splitText.Split(" ")
doc.AddParagraph(New Paragraph(splitText))
' Export docx
doc.SaveAs("textrun.docx")Set Styling
Setting styling for text requires using the Run wrapper pattern. Create a Run object containing TextContent, then assign a TextStyle to the Run (not the TextContent). The TextStyle allows you to define visual attributes such as FontSize, color, bold, italic, strikethrough, underline, superscript, and subscript.
Note that FontSize is configured at the TextStyle level, while FontFamily is set inside the TextFont property. Once styled, use AddChild to add the Run to a paragraph. This follows the document hierarchy: Document → Paragraph → Run → TextContent.
using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;
// Load docx
WordDocument doc = new WordDocument("document.docx");
// Configure text
Run textRun = new Run(new TextContent("Add text using IronWord"));
textRun.Style = new TextStyle()
{
FontSize = 72,
TextFont = new Font()
{
FontFamily = "Caveat"
},
Color = Color.Red,
IsBold = true,
IsItalic = true,
Underline = new Underline(),
Strike = StrikeValue.Strike,
};
Paragraph paragraph = new Paragraph();
// Add text
paragraph.AddChild(textRun);
// Add paragraph
doc.AddParagraph(paragraph);
// Export docx
doc.SaveAs("save_document.docx");Imports IronWord
Imports IronWord.Models
Imports IronWord.Models.Enums
' Load docx
Dim doc As New WordDocument("document.docx")
' Configure text
Dim textRun As New Run(New TextContent("Add text using IronWord"))
textRun.Style = New TextStyle() With {
.FontSize = 72,
.TextFont = New Font() With {
.FontFamily = "Caveat"
},
.Color = Color.Red,
.IsBold = True,
.IsItalic = True,
.Underline = New Underline(),
.Strike = StrikeValue.Strike
}
Dim paragraph As New Paragraph()
' Add text
paragraph.AddChild(textRun)
' Add paragraph
doc.AddParagraph(paragraph)
' Export docx
doc.SaveAs("save_document.docx")Obtain Text Fill Color
Aside from setting styling, IronWord provides a way for you to obtain the RGBA color value from existing documents to retain consistency throughout the styling.
using IronWord;
using IronWord.Models;
using System;
// Open existing Word
WordDocument doc = new WordDocument("Accent1TextThemcolor.docx");
TextContent content = doc.Texts[0];
// This will show the R G B A of the themecolor
var filledColor = content.Color;
// Print the filled color variable to the console
Console.WriteLine(filledColor);To retrieve color values, load the document using WordDocument, then access the Texts collection to obtain the TextContent object. The Color property of TextContent returns the RGBA value of the text's existing color, allowing you to maintain consistent styling throughout your document.
Embed Images
This feature allows you to seamlessly include images within the content, enhancing the overall visual appeal and communicative power of the document.
using IronWord;
using IronWord.Models;
// Load docx
WordDocument doc = new WordDocument();
// Configure image
ImageContent image = new ImageContent("image.jpg");
image.Width = 200; // In unit pixel
image.Height = 200; // In unit pixel
TextContent textRun = new TextContent();
// Add image
Paragraph para = new Paragraph(textRun);
para.AddImage(image);
// Add paragraph
doc.AddParagraph(para);
// Export docx
doc.SaveAs("save_document.docx");Add Images
Load Image
Loading images is a crucial process. This involves bringing external image files into the document. The ability to load images facilitates the inclusion of relevant visuals, contributing to a more engaging and informative document.
using IronWord;
using IronWord.Models;
// Load docx
WordDocument doc = new WordDocument();
Paragraph paragraph = new Paragraph();
// Add image
paragraph.AddImage("image.jpg");
// Add paragraph
doc.AddParagraph(paragraph);
// Export docx
doc.SaveAs("document.docx");Imports IronWord
Imports IronWord.Models
' Load docx
Private doc As New WordDocument()
Private paragraph As New Paragraph()
' Add image
paragraph.AddImage("image.jpg")
' Add paragraph
doc.AddParagraph(paragraph)
' Export docx
doc.SaveAs("document.docx")Configure Image
Optimize the images with configurable settings. This includes setting properties such as dimensions, position, and distance from corners. Proper configuration ensures that images are displayed in a visually pleasing and contextually appropriate manner.
TextWrapBehavior property (type ITextWrapBehavior) for controlling text-wrap around the image, but no public implementing class or factory is currently documented for constructing a value — this example is omitted pending product-team confirmation.using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;
// Load docx
WordDocument doc = new WordDocument();
// Configure image
ImageContent image = new ImageContent("image.jpg");
image.Width = 100;
image.Height = 100;
image.DistanceFromTop = 50;
var position = new ElementPosition();
position.X = 50;
position.Y = 50;
image.Position = position;
Paragraph paragraph = new Paragraph();
// Add image
paragraph.AddImage(image);
// Add paragraph
doc.AddParagraph(paragraph);
// Export docx
doc.SaveAs("document.docx");Frequently Asked Questions
What is IronWord used for in C# development?
IronWord is a powerful library for .NET C# developers designed to assist in creating, reading, and editing Word and DOCX documents within their applications.
How can I add styled text to a Word document using IronWord?
You can add styled text by creating a 'Run' object wrapping 'TextContent', then applying a 'TextStyle' to it and adding it to a paragraph using the 'AddChild' method in IronWord.
What is the purpose of the 'Run' object in IronWord?
The 'Run' object in IronWord acts as a wrapper for 'TextContent' that allows for styling text, such as setting font size, color, and other attributes.
How do you embed an image into a document using IronWord?
To embed an image, create an 'ImageContent' object and add it to a paragraph using the 'AddImage' method. This allows you to insert images seamlessly into your document.
What steps are involved in configuring an image in IronWord?
Configuring an image involves setting properties like dimensions, position, and distance from corners, ensuring the image displays correctly within the document.
Can IronWord retrieve the color values from an existing Word document?
Yes, IronWord can retrieve RGBA color values from existing documents through the 'Color' property of the 'TextContent', helping maintain styling consistency.
What method does IronWord use to split a text run?
IronWord uses the 'Split' method to divide a text run into smaller runs based on a specified delimiter, enabling better organization and manipulation of textual content.
Why is understanding document hierarchy important in IronWord?
Understanding the document hierarchy (Document → Paragraph → Run → TextContent) is crucial for effectively managing and styling content within a Word document using IronWord.
How do you save a Word document created with IronWord?
A Word document created with IronWord can be saved using the 'SaveAs' method, specifying the filename and path for saving the document.
What is the function of the 'AddParagraph' method in IronWord?
The 'AddParagraph' method in IronWord is used to add fully configured paragraphs, with text and images, to a Word document.
Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.
