Codehard.OdtKit 1.0.1

dotnet add package Codehard.OdtKit --version 1.0.1
                    
NuGet\Install-Package Codehard.OdtKit -Version 1.0.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Codehard.OdtKit" Version="1.0.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Codehard.OdtKit" Version="1.0.1" />
                    
Directory.Packages.props
<PackageReference Include="Codehard.OdtKit" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Codehard.OdtKit --version 1.0.1
                    
#r "nuget: Codehard.OdtKit, 1.0.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Codehard.OdtKit@1.0.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Codehard.OdtKit&version=1.0.1
                    
Install as a Cake Addin
#tool nuget:?package=Codehard.OdtKit&version=1.0.1
                    
Install as a Cake Tool

Codehard.OdtKit

NuGet version

A powerful and flexible .NET library for programmatically creating, reading, and modifying OpenDocument Text (.odt) files.

OdtKit simplifies the complexities of the ODF (OpenDocument Format) XML structure by providing a high-level, object-oriented API. It allows developers to treat ODT documents like object models, making it easy to perform complex manipulations such as template filling, table generation, and content editing, all while preserving the integrity of the document.

Key Features

  • Load and Save: Effortlessly read and write .odt documents from/to files, streams, or byte arrays.
  • Object-Oriented XML Manipulation: Interact with ODT elements (<text:p>, <table:table>, etc.) as strongly-typed C# objects.
  • Powerful Template Engine: Use simple C# objects with [Placeholder] attributes to dynamically fill text and image placeholders in your ODT templates.
  • Advanced Table Manipulation: Programmatically create, find, and modify tables. Add, remove, and clone rows with ease.
  • Image Embedding: Easily embed images into your documents and bind them to image placeholders.
  • Built-in Undo/Redo: All manipulations performed through the object wrapper API are automatically tracked, providing a complete history with undo/redo capabilities.
  • Type-Safe Element Wrappers: A comprehensive set of classes representing common ODT elements, reducing the need to work with raw XML and magic strings.

Installation

Install the package via the .NET CLI:

dotnet add package Codehard.OdtKit

Or through the NuGet Package Manager:

Install-Package Codehard.OdtKit

How It Works

OdtKit parses the content.xml of an ODT document into a standard XDocument. To enable safe and easy manipulation, it provides the Wrap() extension method. This method converts a raw XElement into a tree of XElementWrapper objects, which serve as intelligent, type-safe proxies to the underlying XML nodes.

All manipulations performed on these wrapper objects are automatically tracked in a history stack. For example, when you call table.Add(newRow), the library not only adds the XML element but also records an AddOperation. This architecture enables the powerful Undo/Redo feature and provides a robust, transactional way to manage document changes.

The XElementWrapper API

The XElementWrapper is the heart of OdtKit's manipulation capabilities. Once you Wrap() an XElement, you get access to a rich, object-oriented API.

Easily traverse the XML tree using familiar properties.

  • Parent: Gets the parent element.
  • Children: Gets a read-only list of direct child elements.
  • Next: Gets the next sibling element.
  • Previous: Gets the previous sibling element.
  • GetSiblings(): Gets all siblings of the current element.
var paragraph = doc.Wrap().Descendants<PElement>().First();

// Get the element that comes right after the paragraph
var nextElement = paragraph.Next;

// Get all children of the paragraph's parent (i.e., its siblings)
var siblings = paragraph.Parent?.Children;

Manipulation

Modify the document structure with intuitive methods. All these operations are tracked in the history.

  • Add(XElementWrapper child): Adds a new child to the end of the element's children list.
  • AddAfterSelf(XElementWrapper sibling): Adds a new sibling immediately after the current element.
  • AddBeforeSelf(XElementWrapper sibling): Adds a new sibling immediately before the current element.
  • ReplaceWith(XElementWrapper newElement): Replaces the current element with a new one.
  • Remove(): Removes the current element from its parent.
  • RemoveNodes(): Removes all children of the current element.
// Get the first paragraph
var p = doc.Wrap().Descendants<PElement>().First();

// Create a new paragraph
var newP = new PElement(new XElement(OdtDocument.TextNamespace + "p", "A new paragraph."));

// Add it after the first one
p.AddAfterSelf(newP);

// Now, remove the original paragraph
p.Remove();

History (Undo/Redo)

Every wrapper maintains a link to the document's history. You can call Undo() or Redo() from any wrapper instance to revert or re-apply the last operation in the entire document.

  • Undo(): Reverts the last manipulation. Returns true if successful.
  • Redo(): Re-applies the last undone manipulation. Returns true if successful.
var root = doc.Wrap();
var p = root.Descendants<PElement>().First();

// Add a new paragraph
p.AddAfterSelf(new PElement(new XElement(OdtDocument.TextNamespace + "p", "New")));
doc.SaveAs("added.odt");

// The change was made via 'p', but we can undo it from the root
root.Undo();
doc.SaveAs("undone.odt");

// And redo it
root.Redo();
doc.SaveAs("redone.odt");

Querying and Templating

  • Descendants<T>(): Gets all descendant elements of a specific wrapper type (e.g., PElement, TableElement).
  • FillPlaceholders(object model): Finds all <text:placeholder> descendants and fills them with values from a model object marked with [Placeholder] attributes.

Core API Concepts

  • OdtDocument: The main class to load, save, and access the document's Content (as an XDocument).
  • OdtContainer: Manages the collection of files inside the ODT zip archive, including content.xml, images, and manifests.
  • XElementWrapper: The abstract base for all typed element wrappers. It provides the core manipulation, navigation, and history API.
  • XElementExtensions.Wrap(): An extension method on XElement that converts it into a specific XElementWrapper subclass (e.g., TableElement, PElement). This is your entry point into the typed API.
  • Representation Classes: Located in the Codehard.OdtKit.Representations namespace, these classes (TableElement, TableRowElement, PElement, etc.) provide the strongly-typed API for interacting with ODT elements.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License

Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net9.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.1 454 7/24/2025
1.0.0 115 7/15/2025

Initial release.