Создание расширений для word

Введение

Целью создания этой статьи является сделать мини- шпаргалку для создания надстроек VSTO, здесь я попытался объединить собранные разрозненные крупицы информации по созданию надстройки VSTO на языке C# для Excel. Статья не претендует на целостное описание процесса создания надстройки, это скорее, «дорожная карта» для новичков, здесь описывается как по шагам сделать простейшую надстройку над Excel.

Excel представляет собой офисный «швейцарский нож», которым можно решить огромный спектр задач для работы с разнообразными данными. Но, как правило, для простой рутинной работы требуется очень много последовательных действий, которые повторяются из документа в документ. Для облечения рутины в Excel есть инструмент написания макросов VBA, на котором можно выполнить решение по малой автоматизации, сверстать таблицу, поправить шрифты, убрать формулы с листа. Но ограничения VBA очень быстро напомнят о себе, когда макрос начнет разрастаться, потребуется подключения к базе данных компании, получать данные от стороннего интернет ресурса или есть необходимость скрыть исходный код. Еще одно преимущество С# это возможность портировать код макросов на альтернативный офисный пакет без существенных издержек.

Visual Studio Tools for Office (VSTO, Visual Studio Tools для офиса) представляет собой набор средств разработки, позволяющий использовать всю функциональность .NET Framework для написания пользовательских функций офисного пакета. Надстройки, написанные в VSTO, являются полноценными скомпилированными программами, которые дополняют функционал офисного пакета и кастомизируют бизнес-логику конкретной фирмы.

Процесс написания надстройки

Для начала необходимо создать проект и выбрать тип «Надстройка VSTO для Exсel» в нашей любимой, а может не очень Visual Studio 2022, при необходимости выполнить установку соответствующих компонентов. Далее на следующей странице ввести имя проекта и выбрать платформу .NET Framework 4.8, как самую последнею. Увы платформа ограничивает максимально доступную версию используемого языка С# не выше 7.3, и некий «синтаксический сахар» из последних версий будет недоступен, что немного огорчает.

Сразу же при создании проекта открывается файл ThisAddIn.cs, представляющий собой точку доступа к функциям листа Excel, один недостаток, эти функции доступны только в этом файле, и помочь в этом нам сможет следующий код:

//Возвращает объект приложение Excel
public Excel.Application GetApplication()
{
	return Application;
}
//Возвращает объект активная рабочаяя книга
public Excel.Workbook GetActiveWorkBook()
{
	return (Excel.Workbook)Application.ActiveWorkbook;
}
//Возвращает объект активный рабочий лист
public Excel.Worksheet GetActiveWorksheet()
{
	return (Excel.Worksheet)Application.ActiveSheet;
}
//Возвращает объект активная ячейка
public Excel.Range GetActiveCell()
{
	return (Excel.Range)Application.Selection;
}

И теперь прописав в любом месте в приложения ниже идущий код мы можем получить доступ к функциям Excel:

Application application = Globals.ThisAddIn.GetApplication();
Worksheet worksheet = Globals.ThisAddIn.GetActiveWorksheet();
Range cell = Globals.ThisAddIn.GetActiveCell();
Workbook workBook = Globals.ThisAddIn.GetActiveWorkBook();

Данный код проще всего добавить в абстрактный класс и от него наследовать все функции нашего приложения:

protected abstract class AbstractFunctions
{
	protected readonly Application application = Globals.ThisAddIn.GetApplication();
	protected readonly Worksheet worksheet = Globals.ThisAddIn.GetActiveWorksheet();
	protected readonly Range cell = Globals.ThisAddIn.GetActiveCell();
	protected readonly Workbook workBook = Globals.ThisAddIn.GetActiveWorkBook();
	public abstract void Start();  
}

Например, функция удаления формул на выделенном участке листа Excel будет выглядеть таким образом:

internal class DeleteFormula : AbstractFunctions
{
	public override void Start()
	{
		cell.Value = cell.Value;                            //Удаляем формул
		worksheet.get_Range("A1", Type.Missing).Select();   //Фокус на ячейку А1   
	}
}

Далее необходимо добавить ленту Ribbon (Visual Designer) на которой будут располагаться кнопки запуска наших приложений, тут тоже хитрого ничего нет, и добавляется на точно также, как и все элементы в проект:

Далее, в коде нашей ленты мы создаем обработчики нажатий на кнопки, я предпочитаю разносить функции по классам и использовать генерацию события нажатия на кнопку в методе Load(). Это значительно упрощает код визуально и облегчает внедрение зависимостей (Dependency injection):

public partial class Ribbon1
{     
	private void Ribbon1_Load(object sender, RibbonUIEventArgs e)
	{             
		button1.Click += (s, a) =>
		{
			DeleteFormyla deleteFormyla= new DeleteFormyla ();
			DeleteFormyla.Start();
		}
	}
}

Однако, можно создать обработчик кнопок и нажатием двойным кликом, но как говорилось раньше это не самое красивое решение.

Теперь кульминация, запуск и.. Не работает, необходимо создать сертификат надстройки, заходим в Projects-Propertis-Signing, создаем тестовый ключ Create Test Certificate. И теперь Ваша надстройка успешно работает.

Таким образом, за минимум действий можно создать рабочую надстройку Excel.

1. Вступление

Привет всем!

Ранее мной была написана статья о создании расширения для Microsoft Excel на C#, где я описывал, как с помощью библиотеки Excel-DNA можно создать надстройку, с добавлением пользовательского интерфейса на ленту, и дополнительные функции, для приложения Microsoft Excel. Библиотека Excel-DNA, надо сказать, очень неплохая библиотека, но она имеет как свои плюсы, так и очень существенные минусы.

К плюсам этой библиотеки можно отнести то, что она позволяет создавать расширения для Excel начиная с версии 2007 и выше. Так же плюсом является довольно простой интерфейс для создания дополнительных пользовательских функций, позволяя расширить и существенно улучшить встроенный набор функций Excel. Но, на этом, собственно, плюсы и заканчиваются.

А теперь минусы.

Создание визуального интерфейса надстройки на пользовательскую ленту уже не такое удобное и требует дополнительного стороннего приложения в виде какого-нибудь ribbon xml editor, если Вы, конечно, не желаете довольно досконально изучить все особенности xml-разметки ленты ribbon, чтобы создавать её самому, как говориться, ручками. Хотя, если Вы это действительно изучите, то Вам будет конечно же большой плюс.

Но, кроме не самого приятного способа создания пользовательского интерфейса, ещё и взаимодействие с ним не очень удобное. Дело в том, что прямой доступ к ленте ribbon, при использовании библиотеки Excel-DNA, крайне ограничен, и некоторые взаимодействия с элементами на этой ленте можно произвести только посредством хитрых конструкций, основанных на обработчиках событий, да и то надёжность этих конструкций вызывает вопросы.

Ну и ещё один довольно большой минус — это то, что эта библиотека позволяет создавать надстройки исключительно только для Excel, лишая всякой возможности создать надстройку, скажем, для Word. Кстати, именно это ограничение всё время и мотивировало меня найти какую-либо более универсальную технологию для создания надстроек. И такой технологией оказалось VSTO расширение для Microsoft Office.

2. VSTO расширения для Microsoft Office

Что же такое VSTO? VSTO это Visual Studio Tools for Office, то есть это набор инструментов визуальной среды разработки приложений Visual Studio для Office.

Вообще VSTO не является чем-то совсем уж новым, расширения VSTO можно было создавать еще для Office 2013. Но, что важно, не ниже. И это как раз то, что является его довольно большим минусом. Проблема заключается в том, что в организациях, которые когда-то закупили лицензионный Office 2007, он чаще всего так до сих пор и работает. А что, простой, надежный, без лишних прибамбасов, можно сказать на 100% покрывающий все потребности работы с документами, и закупка более новой версии в целом, вроде как и не имеет смысла, можно сказать пустая трата денег. Но вот расширения VSTO на них встанут едва ли, только если может быть с помощью каких-нибудь «костылей». Так что, если появилась потребность в создании собственных надстроек в приложениях Microsoft Office, то это можно считать существенным мотивом к обновлению ПО, если оно не соответствует требованиям.

Как можно понять из названия VSTO, для его создания в первую очередь конечно же нужен Visual Studio,

на данный момент актуальной версией которой является 2019, и его дополнительный инструмент «Разработка надстроек для Office и SharePoint«.

Добавляемые при этом в Visual studio дополнительные шаблоны и предоставляют наборы инструментов для создания надстроек к Word, Excel, PowerPoint и многих других приложений Microsoft.

Так же в дальнейшем наверняка понадобится инструмент для установки своих созданных надстроек на другие компьютеры, и для этого подойдет расширение «Microsoft Visual Studio Installer Projects«,

которое можно установить с помощью инструмента «управление расширениями«.

Надстройку для Office можно создавать как на уровне документа, то есть эта надстройка будет запущена только при открытии конкретного документа, в котором она была создана, так и на уровне приложения, когда надстройка будет запускаться вместе с приложением независимо от открываемого документа.

Принцип создания надстройки для всех приложений (Word, Excel, PowerPoint и т.д.) в общем-то одинаковый. Для начала создаётся некий интерфейс на пользовательскую ленту инструментов, а затем обрабатываются события, инициируемые элементами этого созданного интерфейса, например, нажатие кнопки. Фактически создание надстройки отличаются в основном только объектной моделью приложения, поэтому, прежде чем создавать надстройку, скажем для Word, вначале нужно изучить объектную модель Word, структуру его документа и API, предоставляющий набор методов для работы с ним. Разумеется, то же касается и остальных приложений пакета Microsoft Office.

Кстати у технологии VSTO я вижу еще один минус. Я пока что так и не нашел, как с помощью VSTO просто расширить набор функций Excel, как это возможно посредством библиотеки Excel-DNA, а ведь это весьма полезная функция.

3. Приступаем к разработке надстройки

А теперь пример создания очень простенькой надстройки для Word, которая все что и будет уметь делать, так это вставлять в документ в текущую позицию фразу «Привет Мир!», ну или за место слова «Мир» будет вставляться указанное имя. При этом можно будет оценить преимущества разработки расширений VSTO по отношению к библиотеке Excel-DNA, если Вы читали мою статью об этой библиотеке.

И так, после того как инструмент «Разработка надстроек для Office и SharePoint» будет добавлен в Visual Studio, в нём появятся множество дополнительных шаблонов. Среди этих шаблонов нас в данный момент интересует шаблон «Надстройка VSTO для Word«.

Кстати, как можно увидеть на изображении выше, рядом так же находятся шаблоны для создания Документа VSTO для Word, и Шаблона VSTO для Word, которые позволяют соответственно создать конкретный документ Word, расширенный дополнительным функционалом, или шаблон документа, который далее будет генерировать документы Word.

Создадим новый проект надстройки VSTO для Word и назовём его «HelloWoldAddIn», на что в ответ будет получен следующий автоматически сгенерированный код:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml.Linq;
using Word = Microsoft.Office.Interop.Word;
using Office = Microsoft.Office.Core;
using Microsoft.Office.Tools.Word;

namespace HelloWoldAddIn
{
    public partial class ThisAddIn
    {
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {
        }

        #region Код, автоматически созданный VSTO

        /// <summary>
        /// Требуемый метод для поддержки конструктора — не изменяйте 
        /// содержимое этого метода с помощью редактора кода.
        /// </summary>
        private void InternalStartup()
        {
            this.Startup += new System.EventHandler(ThisAddIn_Startup);
            this.Shutdown += new System.EventHandler(ThisAddIn_Shutdown);
        }
        
        #endregion
    }
}

Класс ThisAddIn, который был автоматически создан, является наследником класса Microsoft.Office.Tools.AddInBase, который, в свою очередь, предоставляет доступ к объектной модели текущего приложения посредством поля Application, возвращающего объект, представляющий экземпляр этого приложения.

Изначально в этом классе представлены всего лишь два обработчика событий — ThisAddIn_Startup, выполняющий код при загрузке надстройки и позволяющий произвести какую-либо инициализацию этой надстройки при запуске приложения. И ThisAddIn_Shutdown, который наоборот выполняет код перед закрытием приложения, и позволит сохранить настройки Вашей надстройки.

Но, с помощью только этих двух обработчиков многого не сделаешь, для работы нужна хотя бы одна какая-нибудь кнопка, которую можно было бы нажать в нужный момент работы с документом. И эту кнопку конечно же можно создать на ленте пользовательского интерфейса. Поэтому следующая задача — добавить в проект «Ленту«, и чтобы было удобнее её редактировать, стоит выбрать именно ленту в визуальном конструкторе,

после чего, собственно, и появится конструктор вкладки TabAddIns на ленте, пока еще пустой. Эту вкладку представляет класс Ribbon1, который является наследником класса Microsoft.Office.Tools.Ribbon.RibbonBase, который, в свою очередь, представляет базовый класс для настроек ленты Microsoft Office.

Далее, используя возможности визуального конструктора, панель элементов и поле свойства элементов, не составит никакого труда создать визуальный вид своей будущей надстройки.

И вот теперь в надстройке наконец-то появилась такая нужная нам кнопка, которую я назвал «Привет Мир!». Так же, для небольшой демонстрации некоторых возможностей, я сразу же добавил текстовое поле «Имя», из которого будет браться указанное имя для замены слова «Мир» во вставляемой этой надстройкой фразе.

При желании можно изменить имя группы вкладки, я свою группу назвал просто «Моя надстройка», а также можно переименовать саму вкладку, имя по умолчанию которой «TabAddIns». Если оставить имя как есть, то надстройка появиться в ленте на общей вкладке под названием «Надстройки», если же переименовать, то название вкладки, в которой появиться надстройка, соответственно измениться.

Далее эту ленту, а точнее вкладку на ленте, надо добавить к нашей надстройке и сделать это можно в переопределенном методе CreateRibbonExtensibilityObject.

protected override IRibbonExtensibility CreateRibbonExtensibilityObject() {
    Ribbon1 ribbon = new Ribbon1();
    return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
        new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { ribbon });
}

И теперь, запустив приложение кнопкой Пуск,

откроется приложение Word, в котором уже можно найти созданную надстройку.

Правда толку от нее мало, кнопка пока что еще не работает. Поэтому, для того чтобы надстройка заработала, осталось на кнопку «Привет мир» добавить какой-нибудь программный код. Для этого находим эту кнопку в конструкторе, и, дважды на неё нажав мышкой, добавляем ей обработчик события, начальный код которого генерируется в классе ленты Ribbon1.

Но далее возникает одна проблемка. Сама лента Ribbon не имеет доступа к Application, и соответственно не может получить экземпляр текущего приложения для работы с ним и его документами. Так что писать код обработчика события нажатия кнопки прямо в классе Ribbon это плохая идея. Но это проблема решается довольно просто — нужно добавить новое событие, например, ButtonClicked, самому классу Ribbon, и при нажатии кнопки на ленте запустить обработчик этого нового события. А сам программный код этого обработчика определить в классе ThisAddIn, который уже вполне имеет доступ к Application. И кроме того, через этот обработчик, основанный на стандартном делегате Action, в класс ThisAddIn можно передать экземпляр текущего класса Ribbon, что позволит получить полноценный доступ к своей вкладке на ленте и всем её компонентам.

    public partial class Ribbon1 {
        public event System.Action<Ribbon1> ButtonClicked;
        private void Ribbon1_Load(object sender, RibbonUIEventArgs e) {
            
        }

        private void btnHelloWorld_Click(object sender, RibbonControlEventArgs e) {
            ButtonClicked?.Invoke(this);
        }
    }

    public partial class ThisAddIn
    {

        . . .

        protected override IRibbonExtensibility CreateRibbonExtensibilityObject() {
            Ribbon1 ribbon = new Ribbon1();
            ribbon.ButtonClicked += Ribbon_ButtonClicked;
            return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { ribbon });
        }

        private void Ribbon_ButtonClicked(Ribbon1 ribbon) {
            // Если в текстовом поле на ленте указано имя, то возьмем его. Иначе имя будет Мир.
            string _name = ribbon.ebHelloWorld.Text == "" ? "Мир" : ribbon.ebHelloWorld.Text;
            // Вставим в текущую позицию текст "Привет" и определенное выше имя.
            Application.Selection.Text = $"Привет {_name}!";
        }
    }

Ну вот надстройка и готова, осталось её запустить, и проверить её работу.

Да, кстати, после того как Вы протестируете надстройку, она останется в приложении Word и после закрытия Visual Studio, что не совсем правильно, так как эта надстройка пока еще только тестовая. Поэтому перед тем как завершить работу в Visual Studio не забудьте очистить собранный проект.

4. Дополнительные возможности надстройки

Надстройки VSTO удобны тем, что они позволяют использовать практически любые библиотеки и возможности NET Framework, версию которой Вы выберите перед началом создания надстройки. А это значит, что при желании Вы можете в документ загрузить какую-нибудь информацию, например, из базы данных или прямо с интернета, можете отправить что-нибудь из документа по электронной почте или даже наоборот получить электронную почту сразу в свой документ.

И конечно же имея такие возможности, наверняка рано или поздно возникнет вопрос с хранением некоторых настроек. Ну, в случае VSTO на уровне документа настройки, наверное, можно было бы хранить прямо в самом документе. В Word это может быть некоторый скрытый текст, с именованной закладкой для быстрого доступа к настройкам. В Excel можно использовать какую-либо ячейку. Но вот в надстройках VSTO на уровне приложения конкретного документа нет. Поэтому в этом случае для хранения настроек подойдёт системный реестр или просто обычный текстовый документ, расположенный, например, в документах текущего пользователя. Вот, как-то так:

public partial class ThisAddIn
{
    const string FILE_NAME = "HelloWordAddIn.txt";
    string name = "";

    private void ThisAddIn_Startup(object sender, System.EventArgs e)
    {
        name = LoadName();
    }

    private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
    {
    }

    #region Код, автоматически созданный VSTO

    /// <summary>
    /// Требуемый метод для поддержки конструктора — не изменяйте 
    /// содержимое этого метода с помощью редактора кода.
    /// </summary>
    private void InternalStartup()
    {
        this.Startup += new System.EventHandler(ThisAddIn_Startup);
        this.Shutdown += new System.EventHandler(ThisAddIn_Shutdown);
    }

    #endregion

    protected override IRibbonExtensibility CreateRibbonExtensibilityObject() {
        Ribbon1 ribbon = new Ribbon1();
        ribbon.ButtonClicked += Ribbon_ButtonClicked;
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { ribbon });
    }

    private void Ribbon_ButtonClicked(Ribbon1 ribbon) {
        // Определим какое имя должно быть указно при нажатии кнопки.
        string _name = 
            ribbon.ebHelloWorld.Text == "" ? (string.IsNullOrEmpty(name) ? "Мир" : name) 
            : ribbon.ebHelloWorld.Text;
        // Вставим в текущую позицию текст "Привет" и определенное выше имя.
        Application.Selection.Text = $"Привет {_name}!";
    }

    /// <summary>
    /// Получает имя из файла в директории "Мои документы"
    /// </summary>
    /// <returns></returns>
    private string LoadName() {
        string _name = "";
        // Для начала надо узнать путь к директорию "Мои документы" 
        // текущего пользователя,
        string myDocuments = 
            Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
        // и сформировать полный путь к текстовому файлу, 
        // в котором должно быть указано имя.
        string path = $@"{myDocuments}{FILE_NAME}";

        // Если этого файла нет,
        if (!File.Exists(path))
            // то надо его создать, и сразу закрыть.
            File.Create(path).Close();

        try {
            // Далее надо открыть текстовый файл,
            using (StreamReader sr = 
                new StreamReader($@"{myDocuments}{FILE_NAME}", Encoding.UTF8)) {
                // и считать из него указанное имя.
               _name = sr.ReadLine();
            }
        } catch (FileNotFoundException) {
            // Если во время открытия файла возникла ошибка, 
            // значит пусть имя останется пустым.
            _name = "";
        }
        return _name != null ? _name : "";
    }
}

В этом коде был добавлен метод LoadName, который находит в директории документов пользователя файл «HelloWordAddIn.txt» и считывает из него имя, которое нужно поприветствовать. Чтобы постоянно не обращаться к файлу, имя считывается один раз при запуске настройки из метода ThisAddIn_Startup, и запоминается в глобальной переменной name, к которой уже в любой момент могут обратиться все желающие.

Единственное что ещё хотелось бы сделать, так это инициализировать пользовательский интерфейс надстройки при запуске, то есть, если в файле настроек указано имя, то чтобы это имя сразу же отображалось в текстовом поле в надстройке на пользовательской ленте.

Сделать это можно в классе ленты Ribbon в методе Ribbon1_Load, который срабатывает при загрузке ленты в приложении Office. Но делать это прямо в классе ленты опять же будет не целесообразно, так как прямой связи с классом ThisAddIn он не имеет, а ведь именно в нём находятся данные для загрузки имени из файла. Зато есть смысл добавить классу Ribbon ещё одно событие RibbonLoad, обработчик которого будет запускаться при загрузке ленты.

И тогда класс Ribbon примет следующий вид:

    public partial class Ribbon1 {
        public event System.Action<Ribbon1> RibbonLoad;
        public event System.Action<Ribbon1> ButtonClicked;

        private void Ribbon1_Load(object sender, RibbonUIEventArgs e) {
            RibbonLoad?.Invoke(this);
        }

        private void btnHelloWorld_Click(object sender, RibbonControlEventArgs e) {
            ButtonClicked?.Invoke(this);
        }
    }

а в классе ThisAddIn тогда немного изменится метод CreateRibbonExtensibilityObject.

    protected override IRibbonExtensibility CreateRibbonExtensibilityObject() {
        Ribbon1 ribbon = new Ribbon1();
        ribbon.RibbonLoad += Ribbon_RibbonLoad;
        ribbon.ButtonClicked += Ribbon_ButtonClicked;
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { ribbon });
    }

В нем добавляется обработчик на новое, только что созданное, событие. И, соответственно, добавиться метод Ribbon_RibbonLoad,

        /// <summary>
        /// Обработка события возникающего при загрузке надстройки на ленте Ribbon
        /// </summary>
        /// <param name="ribbon"></param>
        private void Ribbon_RibbonLoad(Ribbon1 ribbon) {
            ribbon.ebHelloWorld.Text = name;
        }

в котором и происходит инициализация пользовательского интерфейса ленты, а точнее, перед открытием приложения в текстовое поле заносится указанное в файле имя.

5. Ручная установка надстройки

Теперь, когда надстройка готова, её надо установить. Для того чтобы Microsoft Word увидел и подключил надстройку на другом компьютере, проект надстройки надо собрать уже не в режиме разработки (Debug), а в режиме развертывания (Release). В выходном каталоге, примерно где-то здесь: C:UsersUsersourcereposHelloWoldAddInHelloWoldAddInbinRelease, будут скомпилированы несколько файлов. Нас интересуют четыре из них:

• HelloWoldAddIn.dll
• HelloWoldAddIn.dll.manifest
• HelloWoldAddIn.vsto
• Microsoft.Office.Tools.Common.v4.0.Utilities.dll

Все эти четыре файла нужно скопировать куда-нибудь в одну папку. Но, для того чтобы Word увидел надстройку, нужна еще соответствующая запись в системном реестре. А точнее, в ветке реестра HKEY_CURRENT_USERSoftwareMicrosoftOfficeWordAddins (если приложение Excel, то и ветка соответствующая), нужно добавить раздел нашей надстройки, например, HelloWoldAddIn. В этом разделе нужно создать четыре параметра:

• строковый параметр «Description»
• строковый параметр «FriendlyName»
• параметр DWORD (32 бита) «LoadBehavior»
• строковый параметр «Manifest»

и заполнить их примерно как указано на изображении ниже.

Параметр «Description» — это понятно, описание надстройки.

Параметр «FriendlyName» — это то, как надстройка будет выглядеть в списке надстроек в приложении Microsoft.

Параметр «LoadBehavior» равный 3 означает, что надстройка включена.

Самый сложный получается параметр «Manifest«, тут указан путь к файлам надстройки. Но, надо обязательно учесть, что перед началом пути стоит префикс «file:///», да-да, именно с треся слешами, а в конце пути указан суффикс «|vstolocal» и именно с «пайпом» в начале суффикса. А сам путь должен указывать на конкретный файл с расширением «vsto».

Если Вы все правильно сделаете, то запустив приложение Word, после нескольких предупреждений о нарушении безопасности, на ленте интерфейса Вы увидите свою надстройку. А если зайти в параметры Word, то на вкладке «Надстройки» будет информация о добавленной надстройке.

Так же, если зайти в «Управление надстройками COM«, то в списке надстроек будет отображаться Ваша надстройка, которую при желании можно временно отключить, убрав галочку напротив неё.

Если параметры реестра прописаны в ветке «HKEY_CURRENT_USER«, то надстройка будет доступна только текущему пользователю Windows, а если те же параметры прописать в ветке «HKEY_LOCAL_MACHINE«, то надстройка станет доступна для всех пользователей системы.

6. Установка надстройки с помощью установщика Windows

Но конечно же устанавливать надстройку вручную очень неудобно, поэтому гораздо лучше создать установщик, который всё сделает сам. Поэтому, если Вы все ещё не установили себе расширение «Microsoft Visual Studio Installer Projects«, то самое время это сделать.

Далее надо добавить проект установщика (Setup Project) в решение,

после чего сразу откроется вкладка «File System«. Если же она не открылась, то открыть её можно самому, нажав правой кнопкой мыши на проекте установщика, и в появившемся меню из «View» выбрать пункт «Файловая система«.

Во вкладке файловой системы надо указать, какие файлы нужны для работы. Для этого надо вызвать меню правой кнопкой мыши на разделе «Application Folder«, и из пункта «Add» выбрать подпункт «Выходной элемент проекта…«.

Появится окно «Добавление выходной группы проекта«, в котором надо выбрать пункт «Основные выходные файлы» и нажать кнопку «ОК».

После этого в разделе «Application Folder» появится список файлов. Это и есть те файлы, которые далее будут скопированы в рабочий раздел надстройки, и которые должны отвечать за её работу.

Но этот список надо немного скорректировать, что-то надо в него добавить, а что-то из него удалить. А именно.

В этом списке в данный момент не хватает двух важных файлов манифеста надстройки Word:

• HelloWoldAddIn.dll.manifest
• HelloWoldAddIn.vsto

Чтобы их добавить нужно снова вызвать контекстное меню раздела «Application Folder» и из пункта меню «Add» выбрать теперь уже подпункт «Файл…«. Откроется окно выбора файлов, в котором надо найти эти файлы манифеста. Найти их можно, как я уже указывал ранее, в выходном каталоге проекта надстройки, примерно где-то здесь: C:UsersUsersourcereposHelloWoldAddInHelloWoldAddInbinRelease. Если этот каталог пустой, значит Вы просто забыли собрать проект надстройки в режиме развертывания (Release), сделайте это. А далее надо добавить эти два файла в список выходных файлов.

А теперь в списке ещё остались файлы, которые в рабочем каталоге надстройки совершенно не нужны, их надо исключить из списка выходных файлов. Это удобнее делать из окна «Обозревателя решений«. Чтобы исключить файл из списка надо выбрать его в обозревателе, после чего в окне свойств установить значение параметра «Exclude» в True. После этого этот файл в «Обозревателе решений» примет вид как исключённый, а из списка выходных файлов и вовсе исчезнет.

Исключить из списка нужно все файлы из-под раздела обнаруженных зависимостей («Detected Dependencies»), за исключением платформы «Microsoft .NET Framework» или любой сборки, завершающейся ** *.Utilities.dll**

Должно получиться примерно вот так:

Сразу же можно настроить путь к выходным файлам надстройки. Для этого надо выбрать раздел «Application Folder«, после чего в окне свойств в параметре «DefaultLocation» можно будет увидеть шаблон пути: [ProgramFiles64Folder][Manufacturer][ProductName].

ProgramFiles64Folder или ProgramFilesFolder означает путь к директорию Program Files, или Program Files (x86), смотря какую платформу Вы выберите, 64-битную или 32-битную.

Параметры «Manufacturer» и «ProductName» — это переменные, которые можно настроить в окне свойств проекта установщика, после того как будет выбран корень проекта «HelloWorldAddInSetup«.

Здесь же с помощью параметра «TargetPlatform» выбирается платформа, 64-битная (x64) или 32-битная (x86), это важно и зависит от того, для какого офиса будет устанавливаться надстройка, для 64-битного или 32-битного.

Не менее важным параметром является параметр «Version«, который влияет на то, будут ли при переустановке надстройки уже существующие файлы заменены, или будет отображено сообщение, что более новая версия уже установлена. При изменении этого параметра, будет предложено автоматически изменить значение параметра «ProductCode«, сформировав новый уникальный код. Ориентируясь на этот код, установщик будет принимать решение, устанавливается ли измененная надстройка или производится попытка ещё раз установить ту же самую надстройку. Если код разный, то далее уже делается проверка номера версии устанавливаемой надстройки, выше она, уже установленной, или ниже.

Так же здесь настраивается переменная «Author«, которую тоже можно использовать в шаблоне пути выходных файлов.

Еще полезные параметры, которые будут видны при установке надстройки, это «Description» — описание надстройки и «Title» — всплывающая подсказка к надстройке.

Как можно вспомнить из раздела ручной установки надстройки, для её работы кроме файлов нужна ещё запись в системном реестре. Для программной установки записи в реестр надо правой кнопкой вызвать контекстное меню на заголовке проекта установщика, и далее из меню «View» выбрать подменю «Реестр«.

Откроется вкладка Реестра (Registry), в двух ветках которой уже будут начальные записи.

Запись в ветке реестра HKEY_CURRENT_USER означает, что настройка будет установлена только для текущего пользователя. А ветка HKEY_LOCAL_MACHINE — что надстройка будет установлена для всех пользователей операционной системы. Но, в любом случае, начальные записи не верны, поэтому раздел «[Manufacture]» можно смело удалять из обоих веток.

Далее надо решить, будет ли всё-таки устанавливаться надстройка для всех или только для текущего пользователя, и выбрать для дальнейшей работы соответствующую ветку HKEY. В этой ветке к разделу «Software» надо последовательно добавить разделы, чтобы получился следующий путь: HKEY_*SoftwareMicrosoftOfficeWordAddInsParadox.HelloWorldAddIn. Понятно, что в этом пути Word означает надстройку для приложения Microsoft Word, и если надстройка создается, например, для Excel, то за место Word надо указать Excel. А раздел с именем «Paradox.HelloWorldAddIn» это уже непосредственно сама надстройка и может быть названа как угодно по своему усмотрению, но обычно её имя строится из названия организации или автора и названия надстройки через точку.

После того как путь будет построен, в разделе «Paradox.HelloWorldAddIn» следует создать четыре параметра:

• строковый параметр «Description»
• строковый параметр «FriendlyName»
• параметр DWORD (32 бита) «LoadBehavior»
• строковый параметр «Manifest»

и заполнить их аналогично, как это описано в ручной установке надстройки. Должно получиться примерно, как на изображении ниже.

Как можно заметить, в параметре «Manifest«, в отличии от ручной настройки, указан не путь к файлам надстройки, а переменная «[TARGETDIR]«, которая автоматически выстроит путь к директорию, куда будет установлена надстройка. А какой путь выстроит эта переменная, настраивается в свойствах «Application Folder» вкладки «File System» («Файловой системы«). По умолчанию это директорий с указанным наименованием организации и наименованием имени продукта в каталоге Program Files или Program Files (x86), в зависимости от того, какая платформа была выбрана.

Ну и в общем-то для сборки установщика почти всё готово. Можно ещё сделать проверку требуемой версии Microsoft .NET Framework. Для этого надо нажать правой кнопкой мыши на заголовке проекта установщика, в нашем случае это HelloWorldAddInSetup, и из контекстного меню выбрать пункт «Свойство«, после чего появиться окно страницы свойств установщика.

В этом окне надо нажать кнопку «Предварительные требования» (Prerequisites…), которое откроет окно «Необходимые компоненты«, в котором можно выбрать нужную версию .NET Framework, используемую при создании надстройки.

Так как моим приложениям часто приходиться работать на Windows 7, то я обычно рабою с .NET Framework версии 4.5.2.

Microsoft также при создании установщика для надстроек VSTO рекомендует настроить условия запуска для обнаружения среды выполнения VSTO. Но, для непосредственной установки надстройки, это не обязательно, если Вам будет интересно, то дополнительную информацию по настройке установщика можно найти на официальном сайте Microsoft. А без этих проверок надстройка после установки просто либо заработает, если у Вас Office 2013 или выше, или не заработает, если у Вас соответственно Office ниже версии 2013.

Всё, теперь надо убедиться, что режим компиляции установлен как Release и пересобрать проект установщика. В выходном каталоге проекта установщика надстройки будут созданы два файла — HelloWorldAddInSetup.msi и setup.exe, для установки надстройки можно использовать любой из них. Устанавливаем, запускаем Word и пользуемся.

Конструирование интерфейсов чаще всего используется при создании надстроек. Надстройка представляет собой невидимый документ со встроенным VBA-кодом и с собственными дополнениями к интерфейсу, автоматически открываемый приложением при запуске. При запуске он не показывает своё тело (т.е. содержимое документа — текст, рисунки и пр.), а проявляется только своими изменениями в интерфейсе и подключенными макросами. Таким образом, приложение Microsoft Office дополняет свой функционал, и позволяет редактировать другие документы, используя вновь полученные функции.

Документ надстройки для Word имеет расширение .dotm. Фактически, надстройка для Word является обычным шаблоном с поддержкой макросов. Для надстроек Excel и PowerPoint имеются отдельные расширения — .xlam и .ppam соответственно.

Замечу, что надстройки .xlam и .ppam просто так не открываются в приложениях в качестве документа для редактирования, поэтому пока такая надстройка не готова, её сохраняют как обычный документ с поддержкой макросов. А вот шаблон .dotm можно открыть в Word именно как шаблон (по крайней мере, Ribbon XML Editor это делает), поэтому его можно сохранять шаблоном и в процессе разработки надстройки. Однако, я всё же рекомендую действовать единообразно, и исходники надстроек всегда держать в формате обычных документов с поддержкой макросов, и переводить их в шаблоны или надстройки только после полного окончания их разработки.

Итак, давайте попробуем построить надстройку Word, которая будет выглядеть, как отдельная вкладка, и содержать группу с кнопками, выполняющими некоторые действия. Пусть это будут некие действия с пробелами. Замечу, что процесс создания надстройки Excel ничем не отличается от создания надстройки Word и, умея создавать одно, вы будете уметь создавать другое.

Откроем Ribbon XML Editor, откроем в нём наш подопытный документ, и в окно для 2007-го интерфейса скопируем текст интерфейса нашей надстройки:

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">
    <ribbon startFromScratch="false">
        <tabs>
            <tab id="Вкладка1" label="Полезные надстройки" insertBeforeMso="TabHome" keytip="Н">
                <group id="РаботаСПробелами" label="Работа с пробелами">
                    <button 
                        id="УдалитьПовторяющиесяПробелы" 
                        onAction="УдалитьПовторяющиесяПробелы" 
                        label="Удалить повторяющиеся пробелы" 
                        keytip="У" 
                        imageMso="WordArtSpacingMenu" 
                        size="large" 
                        screentip="Удалить повторяющиеся пробелы" 
                        supertip="Найти и заменить все повторяющиеся пробелы одним"/>
                    <button 
                        id="ПробелыВПереносыСтрок" 
                        onAction="ПробелыВПереносыСтрок" 
                        label="Пробелы в переносы строк" 
                        keytip="ПС" 
                        imageMso="PivotExpandField" 
                        size="large" 
                        screentip="Пробелы в переносы строк" 
                        supertip="Найти и заменить все пробелы переносом строки"/>
                    <button 
                        id="ПереносыСтрокВПробелы" 
                        onAction="ПереносыСтрокВПробелы" 
                        label="Переносы строк в пробелы" 
                        keytip="СП" 
                        imageMso="PivotCollapseField" 
                        size="large" 
                        screentip="Переносы строк в пробелы" 
                        supertip="Найти и заменить все переносы строк пробелами"/>                        
                </group>
            </tab>
        </tabs>
    </ribbon>
</customUI>

Ознакомьтесь с кодом интерфейса. Тут всё просто. Надстройка добавляет новую вкладку, и располагает на ней группу работы с пробелами, содержащую три кнопки. Для упрощения примера, в качестве иконок для кнопок я использовал максимально подходящие встроенные изображения. Вы можете использовать вместо них свои собственные, вы это уже умеете.

Первая кнопка удаляет все повторяющиеся пробелы. Довольно полезная функция, учитывая то, что правильная вёрстка в Word вообще не предполагает идущих подряд пробелов. Вторая кнопка преобразует все пробелы в переносы строк, а третья — обратное действие, т.е. переносы строк в пробелы. Тоже нужная функция для работы с последовательностями различных лексем.

Сгенерируем функции обратного вызова (Alt+F11). Скопируем шаблоны в буфер обмена (обращаем внимание на раскладку клавиатуры во избежание появления кракозябр). Закроем окно шаблонов и запустим документ. Перейдём в редактор Бейсика (Alt+F11) и вставим взятые в буфер обмена шаблоны функций вместо наших старых функций модуля RibbonCallbacks.

Теперь осталось написать на Бейсике нужные команды. Очевидно, нам понадобится функция поиска и замены. С помощью штатной функции записи макросов я выяснил, каким кодом осуществляется поиск и замена, и организовал это в виде отдельной функции, которую мы будем использовать внутри наших функций обратного вызова.

Итак, вставляем в код новую функцию:

'НайтиИЗаменить (компонент: button, атрибут: onAction), 2007
Sub НайтиИЗаменить(findString As String, replaceString As String)
    With Selection.Find
        .ClearFormatting
        .Replacement.ClearFormatting
        .Text = findString
        .Replacement.Text = replaceString
        .Forward = True
        .Wrap = wdFindContinue
        .Format = False
        .MatchCase = False
        .MatchWholeWord = False
        .MatchWildcards = False
        .MatchSoundsLike = False
        .MatchAllWordForms = False
        .Execute Replace:=wdReplaceAll
    End With 
End Sub

Функция принимает на вход строку для поиска и строку для замены, а внутри функции вставлен код из макроса, который записывался во время реального поиска и замены. Несомненно, в нём много лишнего, так как все эти параметры наверняка имеют значения по умолчанию. Тем не менее, для надёжности я оставил всё как есть — хуже уж точно не будет.

Теперь заполняем шаблоны процедур обратного вызова:

'УдалитьПовторяющиесяПробелы (компонент: button, атрибут: onAction), 2007
Sub УдалитьПовторяющиесяПробелы(control As IRibbonControl)
Dim NumCharsBefore As Long, NumCharsAfter As Long
    Do
        NumCharsBefore = ActiveDocument.Characters.Count
        Call НайтиИЗаменить("  ", " ")
        NumCharsAfter = ActiveDocument.Characters.Count
    Loop Until NumCharsBefore = NumCharsAfter
End Sub

'ПробелыВПереносыСтрок (компонент: button, атрибут: onAction), 2007
Sub ПробелыВПереносыСтрок(control As IRibbonControl)
    Call НайтиИЗаменить(" ","^p")
End Sub

'ПереносыСтрокВПробелы (компонент: button, атрибут: onAction), 2007
Sub ПереносыСтрокВПробелы(control As IRibbonControl)
    Call НайтиИЗаменить("^p", " ")
    Call НайтиИЗаменить("^w^p", "")
End Sub

Как видите, код элементарен, ничего сложного. В первой функции мы организовываем цикл, в котором сдвоенные пробелы меняем на одинарные, и который будет выполняться до тех пор, пока при очередной его итерации размер текста до и после поиска и замены не останется равным. Это будет означать, что сдвоенных пробелов в тексте уже не осталось.

Две последние функции ещё более элементарны. Там просто вызывается наша функция по поиску и замене, которая меняет пробел на символ абзаца (^p) или наоборот. В последнем случае мы ещё и удаляем появившийся в конце текста из-за неубирающегося символа абзаца лишний пробел (^w — чистое пространство, например, пробелы или табуляция).

Сохраняем код, закрываем редактор Бейсика и сразу проверяем работу кнопок в документе. Замечу, что закрывать редактор Бейсика не обязательно, можно просто сохранить в нём изменения и переключиться в окно документа. Если кнопки заработали, как надо, сохраняем документ как шаблон с макросами (.dotm) в папку:

C:Users[ИмяПользователя]AppDataRoamingMicrosoftWordSTARTUP

Теперь добавим нашу надстройку. Закрываем всё, открываем Word, лезем в Файл -> Параметры -> Надстройки -> Управление, выбираем «Надстройки Word» и нажимаем кнопку «Перейти». В открывшемся окне на первой же вкладке нажимаем «Добавить…» и выбираем наш файл. Нажимаем «ОК», и наша надстройка начинает действовать.

Introduction

Microsoft Word, along with the rest of the Office applications, has an API that can be called by a program to perform operations on the app’s document. If you’ve given this API any thought, you’ve probably considered it something only power users writing VBA scripts would use.

However, that’s not the case: in Word, the powerful API calls the app to perform just about any action the app can perform on its own. Further, you can write an add-in in C# that does everything a regular C# program does. That’s right—the entire .NET Framework is available to your add-in. You end up with a C# program that not only has all of .NET’s functionality, but also Word’s functionality too.

The first question you face when you create a Word add-in is which of two approaches to use: Visual Studio Tools for Office (VSTO) or an add-in that extends the IDTExtensibility2 interface. According to Microsoft, VSTO isn’t for commercial add-ins. (And I’m not sure of when you would want to use it. In fact, when I asked Microsoft P.R. for examples of when you would use VSTO – they could not give me examples either.) However, you should know it is an option. For more information about VSTO, visit MSDN.

In this article, I’ll show you how to create an IDTExtensibility2 Word add-in. To avoid duplicating details the Microsoft Knowledge Base articles explain at great length, I’ll refer you to the articles instead. I’ll also cover the bugs I ran across and the workarounds for them.

First, to create the Word add-in, read Knowledge Base article 302901. Note: as I demonstrate in this article, you don’t create a Microsoft Office System Projects project in Visual Studio. That’s where you go to create a VSTO project.

Now that you have your Word add-in, you can play around with it. However, you’ll soon discover you can’t turn on themes for buttons the way you do for a Windows application. But a solution exists. Knowledge Base article 830033 comes to the rescue. Once again, when you follow the instructions, turning on themes for buttons works perfectly.

Visual Studio performs a bit of magic so it can run your add-in in the debugger. There is a long explanation for this that will appear in Part II of this article.

So create your initial add-in, build it, and install it. Next, go to the Solution Explorer in Visual Studio, right-click on your project, then select Properties. In the Properties dialog, select Configuration Properties | Debugging, and go to the Start Application property. For that property, set the location of WINWORD.exe (for example, it’s C:Program FilesMicrosoft OfficeOFFICE11WINWORD.EXE on my system). Now, you can run or debug from Visual Studio.

I also recommend you never again run the installer on your development machine. Windows seems to get confused by having registry entries for both running the add-in from the debugger and running it as a standard Word add-in. Even if you uninstall the add-in, it appears to cause problems. And if you have to rename your add-in, create a new one with the new name instead, then copy the other files over. Renaming an existing add-in will break because the add-in won’t have any of the registry settings made during the creation process.

Write Your Add-In

Now you’re ready to start writing your add-in. The first step is to look at the documentation for the API so you can see what you can do. You look in the MSDN library. The documentation isn’t there. You try the Word online help. The documentation isn’t there. You search on Microsoft.com, Google, and post in the newsgroups … and the answer is: there is no documentation. Documentation exists for VBA, but not for C#.

It gets worse. The VBA documentation is only available through Word’s online help; the documentation on MSDN is incomplete. And the format for the documentation is likely one you’re not used to, making it hard for you to drill down to the info you need.

You’ll also come across properties that don’t exist. In those cases, you’ll have to call get_Property(). But again, this approach isn’t documented, so you’ll have to try it and see if it works. (Refer to the MSDN article, “Automating Word Using the Word Object Model”.) But wait—there’s more. The .NET API is a COM API designed for VB. So a method that takes two integers, such as Range(int start, int end) is actually declared as Range(ref object start, ref object end). You have to declare two object (not int) variables, assign int values to them, then pass them in. Yet, the int values are not changed by the call and only an int can be passed in.

But wait—there’s even more. I’ve only found this in one place so far but it probably holds elsewhere: there is no Application.NewDocument event (because there is an Application.NewDocument method in the Word API—and C# doesn’t support having an event and a method with the same name). However, you can cast an Application object to an ApplicationClass object, and you can then call ApplicationClass.NewDocument. Problem solved … well, actually, it’s not. The ApplicationClass solution works on some systems, but not on others. (I have no idea why – and could never get a straight answer on this from Microsoft.) But there is a solution. You can also cast the Application object to an ApplicationEvents4_Event object, and you then call the ApplicationEvents4_Event.NewDocument event (ApplicationEvents3_Event.NewDocument in Word 2002). (While this appears to work on all the systems I’ve tested thus far, you might come across systems where it doesn’t work.) So don’t cast objects to ApplicationClass; instead, cast them to ApplicationEvents4_Event objects. And the IntelliSense doesn’t work for the ApplicationEvents4_Event class, so you’ll have to type in the entire line of code, but it will compile and run fine.

Application.WindowSelectionChange is an event I haven’t found a solution for yet. It can always be set, but sometimes it doesn’t fire. And I can’t find any reason for this. I can start Word and it doesn’t fire, but when I exit and immediately restart, it works. It might not work two or three times in a row, but then work ten times in a row. Even when it works, if you enter text or press undo/redo, it doesn’t fire even though it changes the selection. So, it’s not an all selection changes event so much as a some selection changes event.

Enable and Disable Menu Items

Now, say you want to enable or disable menu items, like Word does for Edit, Copy and Edit, and Paste (only enabled if text is selected). An event is fired before the RMB pop-up menu appears. But for the main menu, there is no event before a menu is dropped down. (I know it seems like there must be an event for this, but there isn’t.)

The WindowSelectionChange event is the only method I’ve found to use. However, it’s inefficient because it either fires a lot or doesn’t fire at all, and it doesn’t fire when you enter text (for which there is no event).

So, you’ll need to do two things: first, enable or disable menu items when the selection event fires; and second, in the event handler for menu items that can be enabled or disabled, check when you first enter the event handler, and if the menu items should be disabled, call your menu update method and return. This way, after the user tries to execute that menu item, the menu is correct.

When you create menu objects, you’ll need to keep a couple of things in mind. First, you must store the returned menu objects in a location that will exist for the life of the program. The menus are COM objects, and if no persistent C# object is holding them, they are designated for garbage collection and your events will stop working the next time the garbage collector runs.

Second, the call CommandBarPopup.Controls.Add(MsoControlType.msoControlButton, Type.Missing, Type.Missing, Type.Missing, false) must have false for the final parameter. If this is set to true, as soon as any other add-in sets Application.CustomizationContext to another value, all your menus go away.

Apparently, temporary (the 5^th parameter) isn’t the life of the application, but the life of the present CustomizationContext set as the CustomizationContext. If another add-in changes the CustomizationContext, your menu disappears. Given a user can normally have several add-ins, you can never set the 5^th parameter to true. The downside is you’re adding your menus to the default template (normal if you don’t change it) permanently. I don’t think you can have menus exist for the life of the application, but not have them added to the template.

Give Users a Template

Another approach is to give users a template to use with your add-in. The template doesn’t have to do anything, but on startup, you look for that template and add your menus only if the template exists. You also add your menus to your template. In essence, you’re using the existence of the template as an Attribute. This is a clean way to have your add-in appear only when you want it to and have it not touch any other part of Word.

Each time your program starts, you need to determine if your menu has already been added (CommandBarControl.Tag is useful for this). If it isn’t there, add it. If it is there, either delete it and then add it, or set your events on the existing items. I delete and add it because over the course of writing the program, the menu items change at times. If you delete and add it, save the location of the menu and add it there. If a user customizes her menu by moving the location of your menu, you don’t want to force it back to the original position the next time Word runs.

When you set the menus, this changes the template, and Word normally asks the user when she exits if she wants to save the changed template. To avoid this, get the value of the default Template.Saved before making the changes, and set Template.Saved to that value after you’re done. If the template was not dirty when you first got the value, it will be set back to the clean value upon completion:

private Template TemplateOn 
{ 
  get
  {
    
    
    Templates tpltColl = ThisApplication.Templates; 

    foreach (Template tpltOn in tpltColl)
      if (tpltOn.Name == "MY_TEMPLATE.DOT")
        return tpltOn;
      return ThisApplication.NormalTemplate;
  }
}

...


Template thisTemplate = TemplateOn;


bool clean = thisTemplate.Saved;
ThisApplication.CustomizationContext = thisTemplate;
...

thisTemplate.Saved = clean;

...

One warning: don’t look at the Template.Dirty value using the debugger. The act of looking at it sets it to dirty. This is a true Heisenbug. (The Heisenberg theory is that the act of observing a particle affects the particle.)

And even after you take all these measures, there is one more issue. Sometimes, when you close all documents so you have Word running but no document open, the menu events still fire fine, but calls to CommandBarControl.Enabled throw exceptions. Once you create a new document, the problem usually goes away—unless you have two instances of Word, close the first one, then bring up a document in the second one. Then the problem remains. The solution to this is covered in Part II.

Find Text Within Range

Now for the last bug (in this article, at least, and one I’ve only seen when searching for ranges within table cells). You need to find some text within a certain range. So you set the range and call Range.Find.Execute(). However, this call sometimes returns matching text found outside the range you selected. It can find text before or after the range and return it. If it finds it before, it doesn’t mean the text doesn’t exist in your range, just that Range.Find.Execute() hasn’t gotten here yet. (And yes, it is only supposed to return text inside the passed range – but it will return text outside the range.)

To fix this, you’ll need to set range.Find.Wrap = WdFindWrap.wdFindContinue and keep calling it until you get a find in your range, or it goes past the end of your range. However, there is another problem with this approach. The Find can first return text after your range even though there is text inside your range. In this case, you need to cycle through the entire document until it wraps back to your range to find the text. While this can burn a lot of clock cycles (think of a 200-page document where you have to walk all the way around), it only happens in cases where this bug occurs and, fortunately, those cases are rare.

public Range Find (int startOffset, int endOffset, bool forward, string text) 
{
    
    
    
    int rangeStart = Math.Max(0, startOffset - 1);

    
    int rangeEnd = Math.Min(endOffset + 1, ThisDocument.Content.End);

    object start = rangeStart;
    object end = rangeEnd;
    Range range = ThisDocument.Range (ref start, ref end);
    range.Find.ClearFormatting();
    range.Find.Forward = forward;
    range.Find.Text = text;
    range.Find.Wrap = WdFindWrap.wdFindStop;

    object missingValue = Type.Missing;
    range.Find.Execute(ref missingValue, ref missingValue, 
                ref missingValue, ref missingValue, ref missingValue, 
                ref missingValue, ref missingValue, ref missingValue, 
                ref missingValue, ref missingValue, ref missingValue, 
                ref missingValue, ref missingValue, ref missingValue, 
                ref missingValue);

    
    if (range.Find.Found && (startOffset <= range.Start) 
                             && (range.End <= rangeEnd))
        return range;

    
    
    
    
    
    start = startOffset;
    end = rangeEnd;
    range = ThisDocument.Range (ref start, ref end);
    string docText = range.Text;

    if (docText == null)
        return null;

    int ind = forward ? docText.IndexOf(text) : docText.LastIndexOf(text);
    if (ind == -1)
        return null;

    
    

    int _start = forward ? startOffset : rangeEnd - text.Length;
    while ((startOffset <= _start) && (_start < rangeEnd))
    {
        start = _start;
        end = rangeEnd;
        range = ThisDocument.Range (ref start, ref end);
        docText = range.Text;

        
        

        if ((docText != null) && docText.StartsWith(text))
        {
            
            int endPos = range.Start + text.Length;

            while (endPos < endOffset) 
            {
                range.End = endPos;
                docText = range.Text;
                if (docText == text)
                    break;
                endPos ++;
            }
            return range;
        }
        _start += forward ? 1 : -1;
    }
    return null;
}

All in all, I’d say you should view the Word .NET façade as fragile. Aside from the Find bug, these problems are probably due to the façade and not Word itself. But keep in mind, you might have to experiment to find a way to talk to Word in a way that is solid.

Beyond the bugs I’ve discussed, you’ll want to keep these issues in mind for your add-in. If you need to tie data to the document, use Document.Variables. Two notes about this: first, Document.Variable only accepts strings (I uuencode my data); and second, it has a size limit between 64,000 and 65,000 bytes. Also, if you serialize your data, be aware that .NET sometimes has trouble finding the assembly of your add-in when deserializing the objects. This is a .NET issue, not a Word one.

If you’re going to call the Help methods from your add-in, they require a Control object for the parent window. Given Word isn’t a .NET program, you have no way to convert an hwnd (Word’s main window) to a Control. So for Help, you’ll need to pass a null parent window.

Occasionally (in my case, it’s about once a week), when you’re building the COM add-in shim, you’ll get the error:

stdafx.h(48): error C3506: there is no typelib registered 
            for LIBID '{AC0714F2-3D04-11D1-AE7D-00A0C90F26F4}'

When you get this, go to C:Program FilesCommonFilesDesigner and run the regsvr32 msaddndr.dll command. I have no idea why this happens (sometimes it occurs between two builds when all I’ve done is edit a CS file), but it’s easy to fix.

The add-in you create is a COM add-in, not an automation add-in. To see it, add the tool menu item called curiously enough “COM Add-Ins” to the Tools menu.

Exit All Instances of Word

One issue that can sideswipe you in a myriad of ways is that if you use Outlook, it uses Word for composing messages. Word loads add-ins when the first instance starts, and uses that set of add-ins for all other instances. The only way to reload instances is to exit all instances of Word.

Word also locks the files it’s using, such as the DLL files for add-ins. Again, the executable files for your add-in are locked. If you run the debugger, it appears to lock the PDB files too. So if things become strange—builds fail, files are locked, new changes aren’t executing—make sure you’ve exited Outlook as well as all instances of Word. This isn’t a bug; it’s a correct operation, but it’s not obvious and can be frustrating to figure out.

Winword.exe can also run as an orphan process at times. No copy of Word will be on the screen; Outlook isn’t running; somehow an instance of Word never exited. Again, in this case, you can’t build until you kill that orphan process.

You’ll also come across the standard Visual Studio issue where occasionally you’ll need to exit and restart Visual Studio. This isn’t a Word issue (my work colleagues have the same problem when they’re writing C# Windows application code), and if all else fails, reboot.

Remember that Outlook starts Word without a document. Make sure your add-in handles this. Also keep in mind that because the API was originally from VB, all arrays are 1-based. This is a major pain to remember, but Microsoft does need to keep the API consistent across all .NET languages, and VB was used first for the API, so it wins.

Another issue to watch for is that Word doesn’t display exceptions thrown in your add-in. You can catch exceptions and act on them, but if you don’t catch the exception, it’s never displayed. You have to set your debugger to break on managed exceptions so you can see them, or put a try/catch in every event handler.

An IDTExtensibility2 add-in can run on Word 2002 (VSTO is limited to Word 2003). However, MSDN’s article on installing the Office 10 Primary Interop Assemblies, or PIAs, (see Additional Resources) is wrong or incomplete. You get the PIAs added to the GAC, but you can’t find them with add references – and you cannot select a file in the GAC. So copy the files out of the GAC, add those copied files, and it will then point at the PIAs in the GAC.

What about Word 2000? Supposedly, PIAs can be built for it. I’m still trying to figure this out, and if I do figure it out, look for it to be covered in Part II or Part III. But Microsoft does not provide Word 2000 PIAs.

Okay, you’ve got your add-in working; just a few more minutes and you can ship it to the world—or so it would seem. First comes the fact that if you Authenticode sign your C# DLL, it doesn’t matter to Word. You have to create a COM shim DLL that then calls your C# DLL. The MSDN article “Using the COM Add-in Shim Solution to Deploy Managed COM Add-ins in Office XP” covers this. Note: this does not work for VSTO applications. (To vent for a second: WHY, Why, why didn’t Microsoft set it up so Word accepts signed .NET DLLs as a signed Word add-in?) Follow the article very closely. In a number of cases, if your changes to the shim are just slightly wrong, the shim won’t work. And figuring out what is wrong is not easy. In fact, the only way to fix problems is to keep trying different approaches. There is a lot to cover about the shim add-in, and it is covered in Part II.

IMHO, this is the one place Microsoft really blew it. The shim solution adds a lot of work for every developer (as opposed to Microsoft doing it once up front), makes the whole solution more complex, and there is no way to debug problems with it.

Once you have the shim working, you’ll need to strong name all .NET DLLs, then Authenticode sign all DLLs. This is necessary to run on systems where security is set to High/do not trust add-ins.

There is one final issue you must address for your code to install correctly. Your initial setup program has registry settings in the HKCU for your add-in. These need to be deleted as you are not setting up your .NET code to be the add-in, but the shim instead. In your shim, the ConnectProxy.rgs file sets its add-in registry entries in the HKCU. If you always want to install your add-in for the current user only, this is fine. But if you want to give your users the choice of installing for everyone or installing for just me (and for 98% of you, you should), place the registry settings in the setup program under User/Machine Hive and delete them from ConnectProxk.rgs. (There will be a longer explanation of this in Part II.)

The biggest problem the Word add-in C# API suffers from is neglect, and its issues reside almost entirely in the .NET/C# wrapper and its associated features (such as documentation, signing security, and the shim layer). This means, once you figure out how to work around these issues, you’re left with a solid, powerful engine.

Additional Resources:

• Microsoft Knowledge Base article 302901: “How To Build an Office COM Add-in by Using Visual C# .NET”.
  
• Microsoft Knowledge Base article 830033: “How to apply Windows SP themes to Office COM add-ins”.
• MSDN Library: “Automating Word Using the Word Object Model”.
• MSDN Library: “Using the COM Add-in Shim Solution to Deploy Managed COM Add-ins in Office XP” by Misha Shneerson and Siew-Moi Khor.
• MSDN Library: “Working with the Office XP Primary Interop Assemblies” by Paul Cornell.