Skip to content

Latest commit

 

History

History
280 lines (217 loc) · 14.5 KB

README.md

File metadata and controls

280 lines (217 loc) · 14.5 KB
Raw

OfficeIMO - Microsoft Word .NET Library

OfficeIMO is available as NuGet from the gallery and its preferred way of using it.

nuget downloads nuget version license nuget downloads

If you would like to contact me you can do so via Twitter or LinkedIn.

twitter blog linked

What it's all about

This is a small project (under development) that allows to create Microsoft Word documents (.docx) using .NET. Underneath it uses OpenXML SDK but heavily simplifies it. It was created because working with OpenXML is way too hard for me, and time consuming. I created it for use within the PowerShell module called PSWriteOffice, but thought it may be useful for others to use in the .NET community.

If you want to see what it can do take a look at this blog post.

I used to use the DocX library (which I co-authored/maintained before it was taken over by Xceed) to create Microsoft Word documents, but it only supports .NET Framework, and their newest community license makes the project unusable.

As I am not really a developer, and I hardly know what I'm doing if you know how to help out - please do.

  • If you see bad practice, please open an issue/submit PR.
  • If you know how to do something in OpenXML that could help this project - please open an issue/submit PR
  • If you see something that could work better - please open an issue/submit PR
  • If you see something that I made a fool of myself - please open an issue/submit PR
  • If you see something that works not the way I think it works - please open an issue/submit PR

I hope you get the drift? If it's bad - open an issue/fix it! I don't know what I'm doing! The main thing is - it has to work with .NET Framework 4.7.2, .NET Standard 2.0 and so on.

This project is under development and as such there's a lot of things that can and will change, especially if some people help out.

Platform Status Code Coverage .NET
Windows .NET 4.7.2, NET 4.8, .NET 6.0, .NET 7.0, .NET Standard 2.0, .NET Standard 2.1
Linux .NET 6.0, .NET 7.0, .NET Standard 2.0, .NET Standard 2.1, .NET Core 3.1
MacOs .NET 6.0, .NET 7.0, .NET Standard 2.0, .NET Standard 2.1, .NET Core 3.1

Please share with the community

Please consider sharing a post about OfficeIMO and the value it provides. It really does help!

Share on reddit Share on hacker news Share on twitter Share on facebook Share on linkedin

Features

Here's a list of features currently supported (and probably a lot I forgot) and those that are planned. It's not a closed list, more of TODO, and I'm sure there's more:

TODO List
  • ☑️ Word basics
    • ☑️ Create
    • ☑️ Load
    • ☑️ Save (auto open on save as an option)
    • ☑️ SaveAs (auto open on save as an option)
  • ☑️ Word properties
    • ☑️ Reading basic and custom properties
    • ☑️ Setting basic and custom properties
  • ☑️ Sections
    • ☑️ Add Paragraphs
    • ☑️ Add Headers and Footers (Odd/Even/First)
    • ◼️ Remove Headers and Footers (Odd/Even/First)
    • ◼️ Remove Paragraphs
    • ◼️ Remove Sections
  • ☑️ Headers and Footers in the document (not including sections)
    • ☑️ Add Default, Odd, Even, First
    • ◼️ Remove Default, Odd, Even, First
  • ☑️ Paragraphs/Text and make it bold, underlined, colored and so on
  • ☑️ Paragraphs and change alignment
  • ☑️ Tables
  • ☑️ Images/Pictures (limited support - jpg only / inline type only)
    • ☑️ Add images from file to Word
    • ☑️ Save image from Word to File
    • ◼️ Other image types
    • ◼️ Other location types
  • ☑️ Hyperlinks
    • ☑️ Add HyperLink
    • ☑️ Read HyperLink
    • ◼️ Remove HyperLink
    • ☑️ Change HyperLink
  • ☑️ PageBreaks
    • ☑️ Add PageBreak
    • ☑️ Read PageBreak
    • ☑️ Remove PageBreak
    • ☑️ Change PageBreak
  • ☑️ Bookmarks
    • ☑️ Add Bookmark
    • ☑️ Read Bookmark
    • ☑️ Remove Bookmark
    • ☑️ Change Bookmark
  • ◼️ Comments
    • ☑️ Add comments
    • ☑️ Read comments
    • ◼️ Remove comments
    • ◼️ Track comments
  • ☑️ Fields
    • ◼️ Add Field
    • ☑️ Read Field
    • ◼️ Remove Field
    • ☑️ Change Field
  • ◼️ Shapes
  • ◼️ Charts
  • ◼️ Lists
    • ☑️ Add lists
    • ◼️ Remove lists
  • ◼️ Table of contents
    • ☑️ Add TOC
  • ☑️ Borders
  • ☑️ Background
  • ◼️ Watermarks
    • ☑️ Add watermark
    • ◼️ Remove watermark

Features (oneliners):

This list of features is for times when you want to quickly fix something rather than playing with full features. This features are available as part of WordHelpers class.

  • ☑️ Remove Headers and Footers from a file

Examples

Basic Document with few document properties and paragraph

This short example show how to create Word Document with just one paragraph with Text and few document properties.

using DocumentFormat.OpenXml.Wordprocessing;
using OfficeIMO.Word;

const string filePath = "/path/to/BasicDocument.docx";
using var document = WordDocument.Create(filePath);

document.BuiltinDocumentProperties.Title = "This is my title";
document.BuiltinDocumentProperties.Creator = "Przemysław Kłys";
document.BuiltinDocumentProperties.Keywords = "word, docx, test";

var paragraph = document.AddParagraph("Basic paragraph");
paragraph.ParagraphAlignment = JustificationValues.Center;
paragraph.Color = SixLabors.ImageSharp.Color.Red;

document.Save(true);

Advanced usage of OfficeIMO

This short example shows multiple features of OfficeIMO.Word

using System;
using DocumentFormat.OpenXml.Wordprocessing;
using OfficeIMO.Word;

const string filePath = "/path/to/AdvancedDocument.docx";
using var document = WordDocument.Create(filePath);

// lets add some properties to the document
document.BuiltinDocumentProperties.Title = "Cover Page Templates";
document.BuiltinDocumentProperties.Subject = "How to use Cover Pages with TOC";
document.ApplicationProperties.Company = "Evotec Services";

// we force document to update fields on open, this will be used by TOC
document.Settings.UpdateFieldsOnOpen = true;

// lets add one of multiple added Cover Pages
document.AddCoverPage(CoverPageTemplate.IonDark);

// lets add Table of Content (1 of 2)
document.AddTableOfContent(TableOfContentStyle.Template1);

// lets add page break
document.AddPageBreak();

// lets create a list that will be binded to TOC
var wordListToc = document.AddTableOfContentList(WordListStyle.Headings111);

wordListToc.AddItem("How to add a table to document?");

document.AddParagraph("In the first paragraph I would like to show you how to add a table to the document using one of the 105 built-in styles:");

// adding a table and modifying content
var table = document.AddTable(5, 4, WordTableStyle.GridTable5DarkAccent5);
table.Rows[3].Cells[2].Paragraphs[0].Text = "Adding text to cell";
table.Rows[3].Cells[2].Paragraphs[0].Color = SixLabors.ImageSharp.Color.Blue;
table.Rows[3].Cells[3].Paragraphs[0].Text = "Different cell";

document
    .AddParagraph("As you can see adding a table with some style, and adding content to it ")
    .SetBold()
    .SetUnderline(UnderlineValues.Dotted)
    .AddText("is not really complicated")
    .SetColor(SixLabors.ImageSharp.Color.OrangeRed);

wordListToc.AddItem("How to add a list to document?");

var paragraph = document
    .AddParagraph("Adding lists is similar to ading a table. Just define a list and add list items to it. ")
    .SetText("Remember that you can add anything between list items! ");
paragraph.SetColor(SixLabors.ImageSharp.Color.Blue).SetText("For example TOC List is just another list, but defining a specific style.");

var list = document.AddList(WordListStyle.Bulleted);
list.AddItem("First element of list");
list.AddItem("Second element of list", 1);

var paragraphWithHyperlink = document.AddHyperLink("Go to Evotec Blogs", new Uri("https://evotec.xyz"), true, "URL with tooltip");
// you can also change the hyperlink text, uri later on using properties
paragraphWithHyperlink.Hyperlink.Uri = new Uri("https://evotec.xyz/hub");
paragraphWithHyperlink.ParagraphAlignment = JustificationValues.Center;

list.AddItem("3rd element of list, but added after hyperlink");
list.AddItem("4th element with hyperlink ").AddHyperLink("included.", new Uri("https://evotec.xyz/hub"), addStyle: true);

document.AddParagraph();

var listNumbered = document.AddList(WordListStyle.Heading1ai);
listNumbered.AddItem("Different list number 1");
listNumbered.AddItem("Different list number 2", 1);
listNumbered.AddItem("Different list number 3", 1);
listNumbered.AddItem("Different list number 4", 1);

var section = document.AddSection();
section.PageOrientation = PageOrientationValues.Landscape;
section.PageSettings.PageSize = WordPageSize.A4;

wordListToc.AddItem("Adding headers / footers");

// lets add headers and footers
document.AddHeadersAndFooters();

// adding text to default header
document.Header.Default.AddParagraph("Text added to header - Default");

var section1 = document.AddSection();
section1.PageOrientation = PageOrientationValues.Portrait;
section1.PageSettings.PageSize = WordPageSize.A5;

wordListToc.AddItem("Adding custom properties to document");

document.CustomDocumentProperties.Add("TestProperty", new WordCustomProperty { Value = DateTime.Today });
document.CustomDocumentProperties.Add("MyName", new WordCustomProperty("Some text"));
document.CustomDocumentProperties.Add("IsTodayGreatDay", new WordCustomProperty(true));

document.Save(true);

Tests

In addition to the fact that OfficeIMO.Word uses Unit Tests, Characterization Tests are also used. Characterization test were added in order to not overlook a change that breaks the behavior. These tests are based on Verify ("Snapshot Testing in .NET with Verify"). if you need to add or update a verified snapshot, you can use the powershell script:

$ pwsh -c ./Build/approve-all.ps1