.NET Word API (How It Works For Developers)

The .NET Word API provides developers with robust tools to convert Word documents, and 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;

class Program
{
    static void Main()
    {
        // Load docx
        WordDocument doc = new WordDocument();
        // Create and add styled text to a paragraph
        Paragraph paragraph = new Paragraph();

        // Adding regular text
        paragraph.AddTextRun(new TextRun("Exploring text styles within a document."));

        // Adding italic text
        paragraph.AddTextRun(new TextRun("An example in italic.", new TextStyle { IsItalic = true }));

        // Adding bold text
        paragraph.AddTextRun(new TextRun("An example in bold.", new TextStyle { IsBold = true }));

        // Add paragraph to the document and export docx
        doc.AddParagraph(paragraph);
        doc.SaveAs("newdocument.docx");
    }
}

using IronWord;
using IronWord.Models;

class Program
{
    static void Main()
    {
        // Load docx
        WordDocument doc = new WordDocument();
        // Create and add styled text to a paragraph
        Paragraph paragraph = new Paragraph();

        // Adding regular text
        paragraph.AddTextRun(new TextRun("Exploring text styles within a document."));

        // Adding italic text
        paragraph.AddTextRun(new TextRun("An example in italic.", new TextStyle { IsItalic = true }));

        // Adding bold text
        paragraph.AddTextRun(new TextRun("An example in bold.", new TextStyle { IsBold = true }));

        // Add paragraph to the document and export docx
        doc.AddParagraph(paragraph);
        doc.SaveAs("newdocument.docx");
    }
}

Imports IronWord
Imports IronWord.Models

Friend Class Program
	Shared Sub Main()
		' Load docx
		Dim doc As New WordDocument()
		' Create and add styled text to a paragraph
		Dim paragraph As New Paragraph()

		' Adding regular text
		paragraph.AddTextRun(New TextRun("Exploring text styles within a document."))

		' Adding italic text
		paragraph.AddTextRun(New TextRun("An example in italic.", New TextStyle With {.IsItalic = True}))

		' Adding bold text
		paragraph.AddTextRun(New TextRun("An example in bold.", New TextStyle With {.IsBold = True}))

		' Add paragraph to the document and export docx
		doc.AddParagraph(paragraph)
		doc.SaveAs("newdocument.docx")
	End Sub
End Class

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;

class Program
{
    static void Main()
    {
        // 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;

class Program
{
    static void Main()
    {
        // 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

Friend Class Program
	Shared Sub Main()
		' Create a table cell with a paragraph containing text
		Dim cell As New TableCell(New Paragraph(New TextRun("Sample text")))

		' Configure a common border style for the table
		Dim 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")
	End Sub
End Class

Document Elements

Add TextRuns: This feature focuses on 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 ensures that your images will always be perfectly placed.

using IronWord;
using IronWord.Models;

class Program
{
    static void Main()
    {
        WordDocument doc = new WordDocument();

        // Load and configure the image
        IronWord.Models.Image image = new IronWord.Models.Image("your-image.jpg")
        {
            Width = 200, // In unit pixels
            Height = 200 // In unit pixels
        };

        // Create paragraph, add image, add paragraph to document, and export
        Paragraph paragraph = new Paragraph();
        paragraph.AddImage(image);

        // Add paragraph containing the image to the document
        doc.AddParagraph(paragraph);
        doc.SaveAs("save_document.docx");
    }
}

using IronWord;
using IronWord.Models;

class Program
{
    static void Main()
    {
        WordDocument doc = new WordDocument();

        // Load and configure the image
        IronWord.Models.Image image = new IronWord.Models.Image("your-image.jpg")
        {
            Width = 200, // In unit pixels
            Height = 200 // In unit pixels
        };

        // Create paragraph, add image, add paragraph to document, and export
        Paragraph paragraph = new Paragraph();
        paragraph.AddImage(image);

        // Add paragraph containing the image to the document
        doc.AddParagraph(paragraph);
        doc.SaveAs("save_document.docx");
    }
}

Imports IronWord
Imports IronWord.Models

Friend Class Program
	Shared Sub Main()
		Dim doc As New WordDocument()

		' Load and configure the image
		Dim image As New IronWord.Models.Image("your-image.jpg") With {
			.Width = 200,
			.Height = 200
		}

		' Create paragraph, add image, add paragraph to document, and export
		Dim paragraph As New Paragraph()
		paragraph.AddImage(image)

		' Add paragraph containing the image to the document
		doc.AddParagraph(paragraph)
		doc.SaveAs("save_document.docx")
	End Sub
End Class

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.