.NET Word API (How It Works For Developers)

Introduction

The .NET Word API provides developers with robust tools to convert Word documents, interact with, and manipulate MS Word documents within their applications. This API is designed to streamline the process of working with Microsoft Word documents, making it easier to create, edit, convert, and manage documents programmatically. In this article, we'll explore IronWord to understand its capabilities in manipulating Word documents.

Introduction to IronWord

IronWord is a .NET Word library within the .NET Word API ecosystem, designed specifically for developers who process Microsoft Word documents in their .NET applications. With IronWord, developers can easily read, write, and modify Word documents without needing Microsoft Word installed on the server or client machines. This capability is particularly beneficial for applications that need to automate document processing tasks, such as generating reports, invoices, or personalized correspondence through mail merge functionalities.

Features of IronWord

IronWord provides a comprehensive range of features that cater to various aspects of Word document manipulation. Let's explore each set of features, focusing on how they enable the manipulation and merging of multiple documents, categorized under 'Document Structure' and 'Document Elements'.

Document Structure

Read & Edit Word: With IronWord, you can pull out specific information from your Word documents, such as extracting text for editing or repurposing and retrieving images that may need to be used elsewhere. This capability is vital for applications aimed at merging Word documents and processing the information contained in existing DOCX files.

Multiple Formats: IronWord supports a wide range of file formats, enhancing its utility in converting Word documents within .NET applications.

Edit Page Setup: Tailoring the physical layout of your Word documents is straightforward with IronWord. You can adjust the paper size for various MS Word files to standard or custom dimensions, change the orientation for different sections of your document, set the margins to ensure proper alignment, and even modify the background color for aesthetic purposes or to highlight sections.

Add Paragraphs: IronWord enables the addition and removal of text runs within paragraphs, which is essential for editing and formatting large sections of text. Moreover, you can enhance your paragraphs by inserting images and shapes directly into the text, adjusting the styling to match your design specifications, and setting alignments for a polished look. The ability to add bullets and numbering lists also helps in organizing content more effectively.

using IronWord;
using IronWord.Models;
// Load docx
WordDocument doc = new WordDocument();
// Create and add styled text to a paragraph
Paragraph paragraph = new Paragraph();
paragraph.AddTextRun(new TextRun("Exploring text styles within a document."));
paragraph.AddTextRun(new TextRun("An example in italic.", new TextStyle { IsItalic = true }));
paragraph.AddTextRun(new TextRun("An example in bold.", new TextStyle { IsBold = true }));
// Add paragraph and export docx
doc.AddParagraph(paragraph);
doc.SaveAs("newdocument.docx");

using IronWord;
using IronWord.Models;
// Load docx
WordDocument doc = new WordDocument();
// Create and add styled text to a paragraph
Paragraph paragraph = new Paragraph();
paragraph.AddTextRun(new TextRun("Exploring text styles within a document."));
paragraph.AddTextRun(new TextRun("An example in italic.", new TextStyle { IsItalic = true }));
paragraph.AddTextRun(new TextRun("An example in bold.", new TextStyle { IsBold = true }));
// Add paragraph and export docx
doc.AddParagraph(paragraph);
doc.SaveAs("newdocument.docx");

Imports IronWord
Imports IronWord.Models
' Load docx
Private doc As New WordDocument()
' Create and add styled text to a paragraph
Private paragraph As New Paragraph()
paragraph.AddTextRun(New TextRun("Exploring text styles within a document."))
paragraph.AddTextRun(New TextRun("An example in italic.", New TextStyle With {.IsItalic = True}))
paragraph.AddTextRun(New TextRun("An example in bold.", New TextStyle With {.IsBold = True}))
' Add paragraph and export docx
doc.AddParagraph(paragraph)
doc.SaveAs("newdocument.docx")

Add Tables: Tables are a critical component of DOCX files and are easily manipulated with IronWord, supporting dynamic document generation. You can add or remove rows and columns, an operation that is key for dynamic document generation where the amount of data can vary. Merging and splitting cells give you the versatility to format complex tables, and customizing borders and layout dimensions allows for a polished, professional look.

using IronWord;
using IronWord.Models;
// Create a table cell with a paragraph containing text
TableCell cell = new TableCell(new Paragraph(new TextRun("Sample text")));
// Configure a common border style for the table
BorderStyle borderStyle = new BorderStyle
{
    BorderColor = new IronColor(IronSoftware.Drawing.Color.Black),
    BorderValue = IronWord.Models.Enums.BorderValues.Thick,
    BorderSize = 5
};
// Apply the border style to the cell
cell.Borders = new TableBorders
{
    TopBorder = borderStyle,
    RightBorder = borderStyle,
    BottomBorder = borderStyle,
    LeftBorder = borderStyle
};
// Create a table row and add the same cell twice
TableRow row = new TableRow();
row.AddCell(cell);
row.AddCell(cell);
// Create a table, add the row, then create and export the Word document
Table table = new Table();
table.AddRow(row);
WordDocument doc = new WordDocument(table);
doc.SaveAs("Document.docx");

using IronWord;
using IronWord.Models;
// Create a table cell with a paragraph containing text
TableCell cell = new TableCell(new Paragraph(new TextRun("Sample text")));
// Configure a common border style for the table
BorderStyle borderStyle = new BorderStyle
{
    BorderColor = new IronColor(IronSoftware.Drawing.Color.Black),
    BorderValue = IronWord.Models.Enums.BorderValues.Thick,
    BorderSize = 5
};
// Apply the border style to the cell
cell.Borders = new TableBorders
{
    TopBorder = borderStyle,
    RightBorder = borderStyle,
    BottomBorder = borderStyle,
    LeftBorder = borderStyle
};
// Create a table row and add the same cell twice
TableRow row = new TableRow();
row.AddCell(cell);
row.AddCell(cell);
// Create a table, add the row, then create and export the Word document
Table table = new Table();
table.AddRow(row);
WordDocument doc = new WordDocument(table);
doc.SaveAs("Document.docx");

Imports IronWord
Imports IronWord.Models
' Create a table cell with a paragraph containing text
Private cell As New TableCell(New Paragraph(New TextRun("Sample text")))
' Configure a common border style for the table
Private borderStyle As New BorderStyle With {
	.BorderColor = New IronColor(IronSoftware.Drawing.Color.Black),
	.BorderValue = IronWord.Models.Enums.BorderValues.Thick,
	.BorderSize = 5
}
' Apply the border style to the cell
cell.Borders = New TableBorders With {
	.TopBorder = borderStyle,
	.RightBorder = borderStyle,
	.BottomBorder = borderStyle,
	.LeftBorder = borderStyle
}
' Create a table row and add the same cell twice
Dim row As New TableRow()
row.AddCell(cell)
row.AddCell(cell)
' Create a table, add the row, then create and export the Word document
Dim table As New Table()
table.AddRow(row)
Dim doc As New WordDocument(table)
doc.SaveAs("Document.docx")

Document Elements

Add TextRuns: This feature is all about fine-grained control over the text content. You can add, append and split text runs, which is vital for dynamic document creation. Styling options are extensive, including changing font families, sizes, and colors, as well as adding bold, italics, and other text decorations. You can also embed images within text runs, creating a rich, visually engaging document.

Add Images: IronWord allows for comprehensive image manipulation within Word Documents. You can load images from various sources, wrap text around them seamlessly, and adjust their dimensions to fit your layout. The ability to set the position offset and the distance from the corners of the document means that your images will always be perfectly placed.

using IronWord;
using IronWord.Models;
WordDocument doc = new WordDocument();
IronWord.Models.Image image = new IronWord.Models.Image("your-image.jpg")
{
    Width = 200, // In unit pixel
    Height = 200 // In unit pixel
};
Create paragraph, add image, add paragraph to doc, and export
Paragraph paragraph = new Paragraph();
paragraph.AddImage(image);
doc.AddParagraph(paragraph);
doc.SaveAs("save_document.docx");

using IronWord;
using IronWord.Models;
WordDocument doc = new WordDocument();
IronWord.Models.Image image = new IronWord.Models.Image("your-image.jpg")
{
    Width = 200, // In unit pixel
    Height = 200 // In unit pixel
};
Create paragraph, add image, add paragraph to doc, and export
Paragraph paragraph = new Paragraph();
paragraph.AddImage(image);
doc.AddParagraph(paragraph);
doc.SaveAs("save_document.docx");

Imports IronWord
Imports IronWord.Models
Private doc As New WordDocument()
Private image As New IronWord.Models.Image("your-image.jpg") With {
	.Width = 200,
	.Height = 200
}
Private paragraph, add, add, [and] As Create
paragraph.AddImage(image)
doc.AddParagraph(paragraph)
doc.SaveAs("save_document.docx")

Add Shapes: Shapes can add significant visual impact to a document, and IronWord gives you the tools to insert and customize them with precision. You can set the shape type (like rectangles, circles, arrows, etc.), determine how text should wrap around the shape, specify exact dimensions and positioning, and even rotate shapes to achieve the desired visual effect.

Compatibility

.NET Versions & Project Types

IronWord is designed for broad compatibility within the .NET ecosystem, supporting C#, VB.NET, and F# across various .NET versions, including .NET Core, .NET Standard, and .NET Framework. This ensures its utility in both contemporary and legacy applications. The library's versatility extends to project types, accommodating web, mobile, and desktop applications through integration with Blazor, WebForms, Xamarin, MAUI, WPF, and console applications.

App Environments

In terms of application environments, IronWord is adaptable to Windows, Linux, iOS, and Android platforms, including specific support for containerization and cloud deployment on Docker, Azure, and AWS. This wide-ranging support facilitates development across different environments.

OS & IDE

IronWord is also compatible with major Integrated Development Environments (IDEs) such as Microsoft Visual Studio, ReSharper, and Rider, offering developers flexibility in their choice of tools. Lastly, it supports various operating systems and processor architectures (x64, x86, ARM), ensuring efficient performance across diverse hardware configurations.

Licensing Options

IronWord offers various licensing options to accommodate the needs of different developers and organizations. They offer a perpetual license, which means you pay once and there are no recurring fees. Every license includes one year of product support and updates. The licensing tiers are designed based on the number of developers, locations, and projects you have. You can also get a free trial to get hands-on experience before purchasing a license.

Lite License

This option is tailored for individual developers working solo on a project. It is priced at $749 and covers one developer in a single location.

Plus License

Aimed at small teams, this license, for $1,499, accommodates up to three developers and is applicable for use in three locations across three projects.

Professional License

For larger teams, the Professional License is priced at $2,999 and supports up to ten developers. It's designed to cater to more substantial operations and includes premium support features.

Conclusion

In wrapping up, IronWord emerges as a robust and flexible .NET Word API, offering a range of licensing options to meet the diverse needs of individual developers and teams. Its features enable efficient management and manipulation of Word documents, ensuring compatibility across multiple .NET versions and project types.