Задача: вывести данные в документ Word. На самом деле это очень большая и необъятная тема, примерно как сам Word, 90% возможностей которого не используются обычными пользователями. Сузим до более простой и чаще встречающейся на практике задачи, с которой в своей время пришлось столкнуться мне самому: надо вывести красивую справку, договор, отчет или иной документ Word с добавлением данных из кода C#. Само собой должны поддерживаться версии Word до 2007, так что о новых форматах файлов придется забыть.
Для начала вспомним, что в Word есть такая замечательная вещь как шаблоны. Соответственно большую часть сложного оформления можно вынести в них и из кода открывать шаблон и вставлять данные в нужные места. Для начала ограничимся простыми строками (типовая задача в крупных предприятиях — вставка дат, цифр, фио и тому подобных вещей, договор на сумму такую-то, от такой-то даты с фио таким-то с параметрами объекта такими-то).
Задача на текущую статью: открыть из кода C# шаблон Word и что-то в него вставить. Шаблон в формате .dot приготовим заранее, в том же самом ворде. Для связи с ним будем использовать механизм COM Interoperability (сокращенно Interop), то есть запускать отдельный exe-процесс самого Word и через специальный интерфейс управлять им. Интерфейсы слава богу есть и находятся они в специальных библиотеках, поставляемых вместе с Office, но документация по ним крайне невнятная, поведение местами очень странное и не логичное. В версиях Visual Studio 2010 и выше возможности программирования Office расширены, но текущее руководство действительно и для 2008 студии.
Нам надо
1. Подключить нужные библиотеки
2. Открыть шаблон Word
3. Найти в нем нужное место
4. Вставить в него строку с информацией
1. Проект в студии у нас уже должен быть. В разделе Ссылки/References кликаем правой кнопкой, идем в «Добавить ссылку» и ищем Microsoft.Office.Interop.Word. В параметрах добавленной библиотеки ставим true в Копировать локально/Copy local, так как библиотеку надо копировать вместе с исполняемыми файлами проекта.
В код добавляем соответствующие using
using Word = Microsoft.Office.Interop.Word; using System.Reflection;
2. Теперь вам предстоит провести много времени с замечательным интерфейсом Word, который представляет сам текстовый редактор и его потроха в виде разнообразных обьектов. Сейчас важны два — Application и Document. Переменные для них по ряду не очевидных причин лучше объявлять через интерфейсы.
Word._Application application; Word._Document document;
Так же почти все функции Word требуют объектных параметров, даже если внутри них сидят простые строки и логические значения, так что лучше заранее сделать несколько оберток
Object missingObj = System.Reflection.Missing.Value; Object trueObj = true; Object falseObj = false;
Чтобы запустить Word и открыть в нем шаблон с диска (путь известен), потребуется примерно такой код
//создаем обьект приложения word
application = new Word.Application();
// создаем путь к файлу
Object templatePathObj = "путь к файлу шаблона";;
// если вылетим не этом этапе, приложение останется открытым
try
{
document = application.Documents.Add(ref templatePathObj, ref missingObj, ref missingObj, ref missingObj);
}
catch (Exception error)
{
document.Close(ref falseObj, ref missingObj, ref missingObj);
application.Quit(ref missingObj, ref missingObj, ref missingObj);
document = null;
application = null;
throw error;
}
_application.Visible = true;
Принципиально важны два момента
1. Мы создаем неуправляемый ресурс, который не соберет сборщик мусора — отдельный процесс в памяти с приложением Word, если мы его не закроем и не выведем на экран, он так и останется там висеть до выключения компьютера. Более того такие ворды могут накапливаться незаметно для пользователя, программист-то еще прибьет их вручную. Заботиться о высвобождения неуправляемого ресурса должен программист.
2. По умолчанию Word запускается невидимым, на экран его выводим мы.
Для начала рассмотрим самый простой и примитивный вариант — поиск и замена строки в документе Word. Некоторые программисты так и работают — ставят в шаблон текстовую метку вроде @@nowDate и заменяют ее на нужное значение.
Пришло время познакомится с фундаментом работы с Word — великим и ужасным объектом Range. Его суть сложно описать словами -это некоторый произвольный кусок документа, диапазон (range), который может включать в себя все что угодно — от пары символов, до таблиц, закладок и прочих интересных вещей. Не стоит путать его с Selection — куском документа, выделенным мышкой, который само собой можно конвертировать в Range. Соотвественно нам надо получить Range для всего документа, найти нужную строку внутри него, получить Range для этой строки и уже внутри этого последнего диапазона заменить текст на требуемый. И не стоит забывать, что документ может иметь сложную структуру с колонтитулами и прочей ересью, возможный универсальный метод для замены всех вхождений данной строки:
// обьектные строки для Word
object strToFindObj = strToFind;
object replaceStrObj = replaceStr;
// диапазон документа Word
Word.Range wordRange;
//тип поиска и замены
object replaceTypeObj;
replaceTypeObj = Word.WdReplace.wdReplaceAll;
// обходим все разделы документа
for (int i = 1; i <= _document.Sections.Count; i++)
{
// берем всю секцию диапазоном
wordRange = _document.Sections[i].Range;
/*
Обходим редкий глюк в Find, ПРИЗНАННЫЙ MICROSOFT, метод Execute на некоторых машинах вылетает с ошибкой "Заглушке переданы неправильные данные / Stub received bad data" Подробности: http://support.microsoft.com/default.aspx?scid=kb;en-us;313104
// выполняем метод поиска и замены обьекта диапазона ворд
wordRange.Find.Execute(ref strToFindObj, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref replaceStrObj, ref replaceTypeObj, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing);
*/
Word.Find wordFindObj = wordRange.Find;
object[] wordFindParameters = new object[15] { strToFindObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, replaceStrObj, replaceTypeObj, _missingObj, _missingObj, _missingObj, _missingObj };
wordFindObj.GetType().InvokeMember("Execute", BindingFlags.InvokeMethod, null, wordFindObj, wordFindParameters);
}
Редкий глюк подробно описан здесь.
На самом деле это не самый лучший метод для вставки информации в документ, так как могут возникнуть сложности с уникальными именами для текстовых меток (если текст одной входит в начало другой, данный метод найдет ее и заменит), их совпадением с произвольным текстом и так далее.
Даже если нам надо найти (и например отформатировать) именно строку с текстом внутри документа, лучше всего выдать наружу найденный Range и уже с ним производить разные злодеяния. Получим примерно такой метод:
object stringToFindObj = stringToFind;
Word.Range wordRange;
bool rangeFound;
//в цикле обходим все разделы документа, получаем Range, запускаем поиск
// если поиск вернул true, он долже ужать Range до найденное строки, выходим и возвращаем Range
// обходим все разделы документа
for (int i = 1; i <= _document.Sections.Count; i++)
{
// берем всю секцию диапазоном
wordRange = _document.Sections[i].Range;
/*
// Обходим редкий глюк в Find, ПРИЗНАННЫЙ MICROSOFT, метод Execute на некоторых машинах вылетает с ошибкой "Заглушке переданы неправильные данные / Stub received bad data" Подробности: http://support.microsoft.com/default.aspx?scid=kb;en-us;313104
// выполняем метод поиска и замены обьекта диапазона ворд
rangeFound = wordRange.Find.Execute(ref stringToFindObj, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing);
*/
Word.Find wordFindObj = wordRange.Find;
object[] wordFindParameters = new object[15] { stringToFindObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj };
rangeFound = (bool)wordFindObj.GetType().InvokeMember("Execute", BindingFlags.InvokeMethod, null, wordFindObj, wordFindParameters);
if (rangeFound) { return wordRange; }
}
// если ничего не нашли, возвращаем null
return null;
Простейшее решение проблемы уникальности текста (нужно нам найти Range слова Word, но внутри всего документа оно встречается десятки раз) — искать строку внутри строки, сначала найти уникальную строку, потом не уникальную внутри нее, неэстетично, но дешево, надежно и практично.
// оформляем обьектные параметры
object stringToFindObj = stringToFind;
bool rangeFound;
/*
Обходим редкий глюк в Find, ПРИЗНАННЫЙ MICROSOFT, метод Execute на некоторых машинах вылетает с ошибкой "Заглушке переданы неправильные данные / Stub received bad data"
http://support.microsoft.com/default.aspx?scid=kb;en-us;313104
rangeFound = containerRange.Find.Execute(ref stringToFindObj, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing, ref wordMissing);
*/
Word.Find wordFindObj = containerRange.Find;
object[] wordFindParameters = new object[15] { stringToFindObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj, _missingObj };
rangeFound = (bool)wordFindObj.GetType().InvokeMember("Execute", BindingFlags.InvokeMethod, null, wordFindObj, wordFindParameters);
if (rangeFound) { return containerRange; }
else { return null; }
Если строку надо просто заменить, то сойдет простейшее
_range.Text = "Это текст заменит содержимое Range";
Но так как Range является универсальный контейнером для любого куска документа Word, то его возможности неизмеримо шире, часть их будет рассмотрена в дальнейших заметках.
Если нам надо просто встать в начало документа (и что-то вставить уже туда):
object start = 0; object end = 0; _currentRange = _document.Range(ref start, ref end);
Сохранить документ на диск можно следующим образом
Object pathToSaveObj = pathToSaveString; _document.SaveAs(ref pathToSaveObj, Word.WdSaveFormat.wdFormatDocument, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj, ref _missingObj);
- Работаем с MS Word из C#, часть 0, класс и тестовый проект-пример WinForms
- Работаем с MS Word из C#, часть 1. Открываем шаблон, ищем текст внутри документа
- Работаем с MS Word из C#, часть 2. Вставляем текст на закладку и форматируем
- Работаем с MS Word из C#, часть 3. Работа с таблицами
- Работаем с MS Word из C#, часть 4. Обьединяем несколько файлов в один, считаем количество страниц
- Microsoft.Office.Interop.Word Namespace
- Range Interface
Table of Contents
- Introducing Interop.Word
- Working with the Document
- Find and Replace Text
- Find and replace Bookmarks
- Convert a DOC / DOCX file to PDF
- Export a DOC / DOCX file into a PDF
- From a Byte Array
If you’re working with ASP.NET C# and you need to open, edit or otherwise access a Microsoft Word DOC or DOCX file, you can easily do that using the Microsoft.Office.Interop.Word library package. This post explains how to do so: you might find it useful in case you need to perform such task or whenever you want to read some insights regarding the process.
Introducing Interop.Word
To access the namespace from your ASP.NET project you have two main choices:
- Install the official Microsoft Office primary interop assemblies (PIAs) package on your machine by downloading and executing the runtime installer, then manually add a Reference to the Microsoft.Office.Interop.Word.dll file.
- Install the appropriate NuGet package within Visual Studio using the Package Manager Console.
Needless to say, you should really go for the second option, but we’ll leave that to you.
Working with the Document
As soon as you have the namespace available, you can do the following:
|
// NS alias to avoid writing the required namespace all the time using word = Microsoft.Office.Interop.Word; // […] Application app = new word.Application(); Document doc = app.Documents.Open(filePath); |
Once you have the app and the doc objects you can perform a lot of editing task, such as:
Find and Replace Text
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
var textToFind = «any source text»; var textToReplace = «any replacement text»; var matchCase = true; var matchWholeWord = true; var matchWildcards = false; var matchSoundsLike = false; var matchAllWordForms = false; var forward = true; var wrap = 1; var format = false; var replace = 2; app.Selection.Find.Execute( textToFind, matchCase, matchWholeWord, matchWildcards, matchSoundsLike, matchAllWordForms, forward, wrap, format, textToReplace, replace); |
Find and replace Bookmarks
|
var bookmarkName = «anyName»; var bookmarkNewValue = «anyValue»; if (doc.Bookmarks.Exists(bookmarkName)) { doc.Bookmarks[bookmarkName].Select(); app.Selection.TypeText(bookmarkNewValue); } |
Convert a DOC / DOCX file to PDF
Surprisingly enough, we can even do that with an one-liner thanks to the native «Save As PDF…» feature introduced with Office 2010.
|
doc.SaveAs2(«path-to-pdf-file.pdf», word.WdSaveFormat.wdFormatPDF); |
Export a DOC / DOCX file into a PDF
This one is almost identical to the previous one in terms of results.
|
doc.ExportAsFixedFormat(tmpFile, WdExportFormat.wdExportFormatPDF); |
… and so on.
For additional info regarding word-to-pdf conversion, you can also read this dedicated post: otherwise, keep reading.
What if you have the DOC or DOCX file stored outside the FileSystem, such as in blob-format within a Database? If that’s the case you need to use a temporary file, because most Office Interop methods do not support working with byte arrays, streams and so on.
Here’s a decent workaround you can use:
|
// byte[] fileBytes = getFileBytesFromDB(); var tmpFile = Path.GetTempFileName(); File.WriteAllBytes(tmpFile, fileBytes); Application app = new word.Application(); Document doc = app.Documents.Open(filePath); // .. do your stuff here … doc.Close(); app.Quit(); byte[] newFileBytes = File.ReadAllBytes(tmpFile); File.Delete(tmpFile); |
You might notice that we used the
Close()
method in order to close (and thus save) the file. In case you wan’t to save your changes to the DOC / DOCX file you opened, you need to explicitly say it by adding the
WdSaveOptions.wdDoNotSaveChanges
object parameter in the following way:
|
doc.Close(word.WdSaveOptions.wdDoNotSaveChanges); |
IMPORTANT: Do not underestimate the call to
app.Quit()
! If you don’t do that, the MS Word instance will be left open on your server (see this thread on StackOverflow for more info on that issue). If you want to be sure to avoid such dreadful scenario entirely you should strengthen the given implementation adding a try/catch fallback strategy such as the follow:
|
Application app = null; Document doc = null; try { app = new word.Application(); doc = Document doc = app.Documents.Open(filePath); // .. do your stuff here … doc.Close(); app.Quit(); } catch (Exception e) { if (doc != null) doc.Close(); if (app != null) app.Quit(); } |
Unfortunately these objects don’t implement IDisposable, otherwise it would’ve been even easier.
That’s pretty much it: happy coding!
In a recent post, I extolled the virtues of a wonderful OSS library I had found for working with Excel data programmatically, LinqToExcel. In that post, I also mentioned a fantastic library for working with Word docs as well, and promised to discuss it in my next post. This is that post.
The big pain point in working with MS Word documents programmatically is . . . the Office Interop. To get almost anything done with Word (including simply pulling the text out of the document, you pretty much need to use Interop, which also means you have to have Word installed on the local machine which is consuming your application. Additionally, my understanding is that there are issues with doing Word automation on the server side.
Image by Mohylek — Some Rights Reserved
Interop is essentially a giant wrapper around the ugliness that is COM, and the abstraction layer is thin indeed. If you need to automate MS Office applications, Interop (or going all the way down to the COM level) is pretty much the only way to do it, and obviously, you need to have Office installed on the client machine for it to work at all.
Often times though, we don’t so much need to automate the office application directly so much as get at the contents of Office file (such as Word or Excel files). Dealing with all that Interop nastiness makes this more painful than it needs to be.
Thankfully, the open source DocX by Cathal Coffey solves both problems nicely, and unlike Interop, presents an easy-to-use, highly discoverable API for performing myriad manipulations/extractions against the Word document format (the .docx format, introduced as of Word 2007). Best of all, DocX does not require that Word or any other Office dependencies be installed on the client machine! The full source is available from Coffey’s Codeplex repo, or you can add DocX to your project using Nuget.
10/2/2013 — NOTE: It has been noted by several commentors on Reddit and elsewhere that the MS official library OpenXml serves the same purpose as Docx, and after all, is the «official» library. I disagree — the OpenXml library «does more» but is inherently more complex to use. While it most certainly offers additional functionality not present in DocX, the DocX library creates a much simpler and more meaningful abstraction for what I find to be the most common use-cases working with Word documents programmatically. As always, the choice of libraries is a matter of preference, and to me, one of «Right tool for the job.»
1/23/2014 — NOTE: I mentioned in the opening paragraph the OSS project LinqToExcel, which is a fantastic library. However, LinqToExcel takes a dependency on the Access Database Engine, which can create issues when (for example) deploying to a remote server or other environment where administrative privileges may be limited. I discovered another OSS library with no such dependencies. You can read about it at Use Cross-Platform/OSS ExcelDataReader to Read Excel Files with No Dependencies on Office or ACE
In this post, we will look at a few of the basics for using this exceptionally useful library. Know that under the covers and with a little thought, there is a lot of functionality here beyond what we will look at in this article.
- Getting Started — Create a Word Document Using the DocX Library
- Use DocX to Add Formatted Paragraphs
- Find and Replace Text Using DocX -Merge Templating, Anyone?
- DocX Exposes Many of the Most Useful Parts of the Word Object Model
- C#: Query Excel and .CSV Files Using LinqToExcel
- Additional Resources/Items of Interest
Add DocX to your project using Nuget
NOTE: When adding Nuget packages to your project, consider keeping source control bloat down by using Nuget Package Restore so that packages are downloaded automatically on build rather than cluttering up your repo.
As with LinqToExcel, you can add the DocX library to your Visual Studio solution using the Nuget Package Manager Console by doing:
Install DocX using the Nuget Package Manager Console:
PM> Install-Package DocX
Alternatively, you can use the Solution Explorer. Right-click on the Solution, select «Manager Nuget Packages for Solution,» and type «DocX in the search box (make sure you have selected «Online» in the left-hand menu). When you have located the DocX package, click Install:
Install DocX using the Nuget Package Manager GUI in VS Solution Explorer:
Getting Started – Create a Word Document Using the DocX Library
Wanna Quickly create a Word-compatible, .docx format document on the fly from your code? Do this (I am assuming you have Word installed on your local machine):
(Note – change the file path to reflect your own machine)
A Really Simple Example:
using Novacode; using System; using System.Diagnostics; namespace BlogSandbox { public class DocX_Examples { public void CreateSampleDocument() { string fileName = @"D:UsersJohnDocumentsDocXExample.docx"; var doc = DocX.Create(fileName); doc.InsertParagraph("This is my first paragraph"); doc.Save(); Process.Start("WINWORD.EXE", fileName); } } }
Note in the above we need to add using Novacode; to our namespace imports at the top of the file. The DocX library is contained within this namespace. If you run the code above, a word document should open like this:
Output of Really Simple Example Code:
What we did in the above example was:
- Create an in-memory instance of a
DocXobject with a file name passed in as part of the constructor. - Insert a
DocX.Paragraphobject containing some text. - Save the result to disc as a properly formatted
.docxfile.
Until we execute the Save() method, we are working with the XML representation of our new document in memory. Once we save the file to disc, we find a standard Word-compatible file in our Documents/ directory.
Use DocX to Add Formatted Paragraphs – A More Useful Example
A slightly more useful example might be to create a document with some more complex formatted text:
Create Multiple Paragraphs with Basic Formatting:
public void CreateSampleDocument() { string fileName = @"D:UsersJohnDocumentsDocXExample.docx"; string headlineText = "Constitution of the United States"; string paraOne = "" + "We the People of the United States, in Order to form a more perfect Union, " + "establish Justice, insure domestic Tranquility, provide for the common defence, " + "promote the general Welfare, and secure the Blessings of Liberty to ourselves " + "and our Posterity, do ordain and establish this Constitution for the United " + "States of America."; var headLineFormat = new Formatting(); headLineFormat.FontFamily = new System.Drawing.FontFamily("Arial Black"); headLineFormat.Size = 18D; headLineFormat.Position = 12; var paraFormat = new Formatting(); paraFormat.FontFamily = new System.Drawing.FontFamily("Calibri"); paraFormat.Size = 10D; var doc = DocX.Create(fileName); doc.InsertParagraph(headlineText, false, headLineFormat); doc.InsertParagraph(paraOne, false, paraFormat); doc.Save(); Process.Start("WINWORD.EXE", fileName); }
Here, we have created some Formatting objects in advance, and then passed them as parameters to the InsertParagraph method for each of the two paragraphs we create in our code. When the code executes, Word opens and we see this:
Output from Creating Multiple Formatted Paragraphs
In the above, the FontFamily and Size properties of the Formatting object are self-evident. The Position property determines the spacing between the current paragraph and the next.
We can also grab a reference to a paragraph object itself and adjust various properties. Instead of creating a Formatting object for our headline like we did in the previous example, we could grab a reference as the return from the InsertParagraph method and muck about:
Applying Formatting to a Paragraph Using the Property Accessors:
Paragraph headline = doc.InsertParagraph(headlineText); headline.Color(System.Drawing.Color.Blue); headline.Font(new System.Drawing.FontFamily("Comic Sans MS")); headline.Bold(); headline.Position(12D); headline.FontSize(18D);
This time, when the program executes, we see THIS:
OH NO YOU DID NOT!
Yes, yes I DID print that headline in Comic Sans. Just, you know, so you could see the difference in formatting.
There is a lot that can be done with text formatting in a DocX document. Headers/Footers, paragraphs, and individual words and characters. Importantly, most of the things you might go looking for are easily discoverable – in other words, the author has done a great job building out his API.
Find and Replace Text Using DocX — Merge Templating, Anyone?
Of course, one of the most common things we might want to do is scan a pre-existing document, and replace certain text. Think templating here. For example, performing a standard Word Merge is not very doable on your web server, but using DocX, we can accomplish the same thing. The following example is simple due to space constraints, but you can see the possibilities:
First, just for kicks, we will create an initial document programmatically in one method, then write another method to find and replace certain text in the document:
Create a Sample Document:
private DocX GetRejectionLetterTemplate() { string fileName = @"D:UsersJohnDocumentsDocXExample.docx"; string headerText = "Rejection Letter"; string letterBodyText = DateTime.Now.ToShortDateString(); string paraTwo = "" + "Dear %APPLICANT%" + Environment.NewLine + Environment.NewLine + "I am writing to thank you for your resume. Unfortunately, your skills and " + "experience do not match our needs at the present time. We will keep your " + "resume in our circular file for future reference. Don't call us, " + "we'll call you. " + Environment.NewLine + Environment.NewLine + "Sincerely, " + Environment.NewLine + Environment.NewLine + "Jim Smith, Corporate Hiring Manager"; var titleFormat = new Formatting(); titleFormat.FontFamily = new System.Drawing.FontFamily("Arial Black"); titleFormat.Size = 18D; titleFormat.Position = 12; var paraFormat = new Formatting(); paraFormat.FontFamily = new System.Drawing.FontFamily("Calibri"); paraFormat.Size = 10D; titleFormat.Position = 12; var doc = DocX.Create(fileName); Paragraph title = doc.InsertParagraph(headerText, false, titleFormat); title.Alignment = Alignment.center; doc.InsertParagraph(Environment.NewLine); Paragraph letterBody = doc.InsertParagraph(letterBodyText, false, paraFormat); letterBody.Alignment = Alignment.both; doc.InsertParagraph(Environment.NewLine); doc.InsertParagraph(paraTwo, false, paraFormat); return doc; }
See the %APPLICANT% placeholder? That is my replacement target (a poor-man’s merge field, if you will). Now that we have a private method to generate a document template of sorts, let’s add a public method to perform a replacement action:
Find and Replace Text in a Word Document Using DocX:
public void CreateRejectionLetter(string applicantField, string applicantName) { string fileNameTemplate = @"D:UsersJohnDocumentsRejection-Letter-{0}-{1}.docx"; string outputFileName = string.Format(fileNameTemplate, applicantName, DateTime.Now.ToString("MM-dd-yy")); DocX letter = this.GetRejectionLetterTemplate(); letter.ReplaceText(applicantField, applicantName); letter.SaveAs(outputFileName); Process.Start("WINWORD.EXE", """ + outputFileName + """); }
Now, when we run the code above, our output is thus:
Obviously, the preceding example was a little contrived and overly simple. But you can see the potential . . . If our letter contained additional «merge fields, we could just as easily pass in a Dictionary<string, string>, where the Dictionary contains one or more Key Value Pairs containing a replacement target and a replacement value. Then we could iterate, using the Dictionary Keys as the search string, and replace with the Dictionary values.
DocX Exposes Many of the Most Useful Parts of the Word Object Model
In this quick article, we have only scratched the surface. DocX exposes most of the stuff we commonly wish we could get to within a Word document (Tables, Pictures, Headers, Footers, Shapes, etc.) without forcing us to navigate the crusty Interop model. This also saves us from some of the COM de-referencing issues which often arise when automating Word within an application. Ever had a bunch of «orphaned» instances of Word (or Excel, etc.) running in the background, visible only in the Windows Task Manager? Yeah, I thought so . . .
If you need to generate or work with Word documents on a server, this is a great tool as well. No dependencies on MS Office, no need to have Word running. You can generate Word documents on the fly, and/or from templates, ready to be downloaded.
I strongly recommend you check out the project on Codeplex. Also, the project author, Cathal Coffey, discusses much of the DocX functionality on his own blog. If you dig DocX, drop by and let him know. He’s really done a fantastic job.
Additional Resources/Items of Interest
- Extending Identity Accounts and Implementing Role-Based Authentication in ASP.NET MVC 5
- C#: Query Excel and .CSV Files Using LinqToExcel
- Splitting and Merging Pdf Files in C# Using iTextSharp
- Working with PDF Files in C# Using PdfBox and IKVM
- Customizing Routes in ASP.NET MVC
- Routing Basics in ASP.NET MVC
- Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
- Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
My name is John Atten, and my username on many of my online accounts is xivSolutions. I am Fascinated by all things technology and software development. I work mostly with C#, Javascript/Node.js, Various flavors of databases, and anything else I find interesting. I am always looking for new information, and value your feedback (especially where I got something wrong!)
Image by Mohylek – Some Rights Reserved
In a recent post, I extolled the virtues of a wonderful OSS library I had found for working with Excel data programmatically, LinqToExcel. In that post, I also mentioned a fantastic library for working with Word docs as well, and promised to discuss it in my next post. This is that post.
The big pain point in working with MS Word documents programmatically is . . . the Office Interop. To get almost anything done with Word (including simply pulling the text out of the document, you pretty much need to use Interop, which also means you have to have Word installed on the local machine which is consuming your application. Additionally, my understanding is that there are issues with doing Word automation on the server side.
Interop is essentially a giant wrapper around the ugliness that is COM, and the abstraction layer is thin indeed. If you need to automate MS Office applications, Interop (or going all the way down to the COM level) is pretty much the only way to do it, and obviously, you need to have Office installed on the client machine for it to work at all.
Often times though, we don’t so much need to automate the office application directly so much as get at the contents of Office file (such as Word or Excel files). Dealing with all that Interop nastiness makes this more painful than it needs to be.
Thankfully, the open source DocX library by Cathal Coffey solves both problems nicely, and unlike Interop, presents an easy-to-use, highly discoverable API for performing myriad manipulations/extractions against the Word document format (the .docx format, introduced as of Word 2007). Best of all, DocX does not require that Word or any other Office dependencies be installed on the client machine! The full source is available from Coffey’s Codeplex repo, or you can add DocX to your project using Nuget.
In this post, we will look at a few of the basics for using this exceptionally useful library. Know that under the covers and with a little thought, there is a lot of functionality here beyond what we will look at in this article.
- Getting Started – Create a Word Document Using the DocX Library
- Use DocX to Add Formatted Paragraphs
- Find and Replace Text Using DocX -Merge Templating, Anyone?
- DocX Exposes Many of the Most Useful Parts of the Word Object Model
- Additional Resources/Items of Interest
Add DocX to your project using Nuget
As with LinqToExcel, you can add the DocX library to your Visual Studio solution using the Nuget Package Manager Console by doing:
Install DocX using the Nuget Package Manager Console:
PM> Install-Package DocX
Alternatively, you can use the Solution Explorer. Right-click on the Solution, select “Manager Nuget Packages for Solution,” and type “DocX in the search box (make sure you have selected “Online” in the left-hand menu). When you have located the DocX package, click Install:
Install DocX using the Nuget Package Manager GUI in VS Solution Explorer:
Getting Started – Create a Word Document Using the DocX Library
Wanna Quickly create a Word-compatible, .docx format document on the fly from your code? Do this (I am assuming you have Word installed on your local machine):
(Note – change the file path to reflect your own machine)
A Really Simple Example:
using Novacode;
using System;
using System.Diagnostics;
namespace BlogSandbox
{
public class DocX_Examples
{
public void CreateSampleDocument()
{
// Modify to siut your machine:
string fileName = @"D:UsersJohnDocumentsDocXExample.docx";
// Create a document in memory:
var doc = DocX.Create(fileName);
// Insert a paragrpah:
doc.InsertParagraph("This is my first paragraph");
// Save to the output directory:
doc.Save();
// Open in Word:
Process.Start("WINWORD.EXE", fileName);
}
}
}
Note in the above we need to add using Novacode; to our namespace imports at the top of the file. The DocX library is contained within this namespace. If you run the code above, a word document should open like this:
Output of Really Simple Example Code:
What we did in the above example was:
- Create an in-memory instance of a
DocXobject with a file name passed in as part of the constructor. - Insert a
DocX.Paragraphobject containing some text. - Save the result to disc as a properly formatted .docx file.
Until we execute the Save() method, we are working with the XML representation of our new document in memory. Once we save the file to disc, we find a standard Word-compatible file in our Documents directory.
Use DocX to Add Formatted Paragraphs – A More Useful Example
A slightly more useful example might be to create a document with some more complex formatted text:
Create Multiple Paragraphs with Basic Formatting:
public void CreateSampleDocument()
{
string fileName = @"D:UsersJohnDocumentsDocXExample.docx";
string headlineText = "Constitution of the United States";
string paraOne = ""
+ "We the People of the United States, in Order to form a more perfect Union, "
+ "establish Justice, insure domestic Tranquility, provide for the common defence, "
+ "promote the general Welfare, and secure the Blessings of Liberty to ourselves "
+ "and our Posterity, do ordain and establish this Constitution for the United States of America.";
// A formatting object for our headline:
var headLineFormat = new Formatting();
headLineFormat.FontFamily = new System.Drawing.FontFamily("Arial Black");
headLineFormat.Size = 18D;
headLineFormat.Position = 12;
// A formatting object for our normal paragraph text:
var paraFormat = new Formatting();
paraFormat.FontFamily = new System.Drawing.FontFamily("Calibri");
paraFormat.Size = 10D;
// Create the document in memory:
var doc = DocX.Create(fileName);
// Insert the now text obejcts;
doc.InsertParagraph(headlineText, false, headLineFormat);
doc.InsertParagraph(paraOne, false, paraFormat);
// Save to the output directory:
doc.Save();
// Open in Word:
Process.Start("WINWORD.EXE", fileName);
}
Here, we have created some DocX.Formatting objects in advance, and then passed them as parameters to the InsertParagraph method for each of the two paragraphs we create in our code. When the code executes, Word opens and we see this:
Output from Creating Multiple Formatted Paragraphs
In the above, the FontFamily and Size properties of the Formatting object are self-evident. The Position property determines the spacing between the current paragraph and the next.
We can also grab a reference to a paragraph object itself and adjust various properties. Instead of creating a Formatting object for our headline like we did in the previous example, we could grab a reference as the return from the InsertParagraph method and muck about:
Applying Formatting to a Paragraph Using the Property Accessors:
// Insert the Headline and do some formatting:
Paragraph headline = doc.InsertParagraph(headlineText);
headline.Color(System.Drawing.Color.Blue);
headline.Font(new System.Drawing.FontFamily("Comic Sans MS"));
headline.Bold();
headline.Position(12D);
headline.FontSize(18D);
This time, when the program executes, we see THIS:
OH NO YOU DID NOT!
Yes, yes I DID print that headline in Comic Sans. Just, you know, so you could see the difference in formatting.
There is a lot that can be done with text formatting in a DocX document. Headers/Footers, paragraphs, and individual words and characters. Importantly, most of the things you might go looking for are easily discoverable – in other words, the author has done a great job building out his API.
Find and Replace Text Using DocX – Merge Templating, Anyone?
Of course, one of the most common things we might want to do is scan a pre-existing document, and replace certain text. Think templating here. For example, performing a standard Word Merge is not very doable on your web server, but using DocX, we can accomplish the same thing. The following example is simple due to space constraints, but you can see the possibilities:
First, just for kicks, we will create an initial document programmatically in one method, then write another method to find and replace certain text in the document:
Create a Sample Document:
private DocX GetRejectionLetterTemplate()
{
// Adjust the path so suit your machine:
string fileName = @"D:UsersJohnDocumentsDocXExample.docx";
// Set up our paragraph contents:
string headerText = "Rejection Letter";
string letterBodyText = DateTime.Now.ToShortDateString();
string paraTwo = ""
+ "Dear %APPLICANT%" + Environment.NewLine + Environment.NewLine
+ "I am writing to thank you for your resume. Unfortunately, your skills and "
+ "experience do not match our needs at the present time. We will keep your "
+ "resume in our circular file for future reference. Don't call us, we'll call you. "
+ Environment.NewLine + Environment.NewLine
+ "Sincerely, "
+ Environment.NewLine + Environment.NewLine
+ "Jim Smith, Corporate Hiring Manager";
// Title Formatting:
var titleFormat = new Formatting();
titleFormat.FontFamily = new System.Drawing.FontFamily("Arial Black");
titleFormat.Size = 18D;
titleFormat.Position = 12;
// Body Formatting
var paraFormat = new Formatting();
paraFormat.FontFamily = new System.Drawing.FontFamily("Calibri");
paraFormat.Size = 10D;
titleFormat.Position = 12;
// Create the document in memory:
var doc = DocX.Create(fileName);
// Insert each prargraph, with appropriate spacing and alignment:
Paragraph title = doc.InsertParagraph(headerText, false, titleFormat);
title.Alignment = Alignment.center;
doc.InsertParagraph(Environment.NewLine);
Paragraph letterBody = doc.InsertParagraph(letterBodyText, false, paraFormat);
letterBody.Alignment = Alignment.both;
doc.InsertParagraph(Environment.NewLine);
doc.InsertParagraph(paraTwo, false, paraFormat);
return doc;
}
See the %APPLICANT% placeholder? That is my replacement target (a poor-man’s merge field, if you will). Now that we have a private method to generate a document template of sorts, let’s add a public method to perform a replacement action:
Find and Replace Text in a Word Document Using DocX:
public void CreateRejectionLetter(string applicantField, string applicantName)
{
// We will need a file name for our output file (change to suit your machine):
string fileNameTemplate = @"D:UsersJohnDocumentsRejection-Letter-{0}-{1}.docx";
// Let's save the file with a meaningful name, including the applicant name and the letter date:
string outputFileName = string.Format(fileNameTemplate, applicantName, DateTime.Now.ToString("MM-dd-yy"));
// Grab a reference to our document template:
DocX letter = this.GetRejectionLetterTemplate();
// Perform the replace:
letter.ReplaceText(applicantField, applicantName);
// Save as New filename:
letter.SaveAs(outputFileName);
// Open in word:
Process.Start("WINWORD.EXE", """ + outputFileName + """);
}
Now, when we run the code above, our output is thus:
Obviously, the preceding example was a little contrived and overly simple. But you can see the potential . . . If our letter contained additional “merge fields, we could just as easily pass in a Dictionary<string, string>, where the Dictionary contains one or more Key Value Pairs containing a replacement target and a replacement value. Then we could iterate, using the Dictionary Keys as the search string, and replace with the Dictionary values.
DocX Exposes Many of the Most Useful Parts of the Word Object Model
In this quick article, we have only scratched the surface. DocX exposes most of the stuff we commonly wish we could get to within a Word document (Tables, Pictures, Headers, Footers, Shapes, etc.) without forcing us to navigate the crusty Interop model. This also saves us from some of the COM de-referencing issues which often arise when automating Word within an application. Ever had a bunch of “orphaned” instances of Word (or Excel, etc.) running in the background, visible only in the Windows Task Manager? Yeah, I thought so . . .
If you need to generate or work with Word documents on a server, this is a great tool as well. No dependencies on MS Office, no need to have Word running. You can generate Word documents on the fly, and/or from templates, ready to be downloaded.
I strongly recommend you check out the project on Codeplex. Also, the project author, Cathal Coffey, discusses much of the DocX functionality on his own blog. If you dig DocX, drop by and let him know. He’s really done a fantastic job.
Additional Resources/Items of Interest
- C#: Query Excel and .CSV Files Using LinqToExcel
- Splitting and Merging Pdf Files in C# Using iTextSharp
- Working with Pdf Files in C# Using PdfBox and IKVM
- Customizing Routes in ASP.NET MVC
- Routing Basics in ASP.NET MVC
- Building Out a Clean, REST-ful Web Api Service with a Minimal Web Api Project
- Creating a Clean, Minimal-Footprint ASP.NET WebAPI Project with VS 2012 and ASP.NET MVC 4
