Как создать надстройку для excel в visual studio

Введение

Целью создания этой статьи является сделать мини- шпаргалку для создания надстроек 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.

You can download the source code from this link Source
Code Link

Introduction

The main purpose of this article is to explain how to create simple Excel and Microsoft Word Add-Ins using Visual
Studio Tools for Office (VSTO).
VSTO is available as an add-in tool with Microsoft Visual Studio. Using Visual Studio we can develop our own custom controls for Office tools like Excel, Word and and so on.In
our demo program We have used Visual Studio 2010 and Office 2007.

Building the Sample

This article explains a few basic things to create our own Custom Add-Ins for Excel and Word as follows.

1. Excel Add-Ins

• Add text to any Excel selected active Excel cell.
• Add an image to Excel from our Custom Control.
• Load data from a database and display the search result data in Excel.

2. Word Add-Ins

• Export Word to PDF.
• Add Image to Word Document.
• Add Table to Word document.

Description

Step 2

Now we can see that the Excel ThisAddIn.Cs file has been created in our project folder and we can find two default methods in this class as in the following image. “ThisAddIn_Startup”
In this event we can display our own custom Control Add-Ins to Excel. We can see the details in the code part.

Step 3

In our example,We are performing 3 types of actions in User Controls.

1. Add Text: In this button click event I will insert the text from the Text box to the Active Selected Excel Cell. Using “Globals.ThisAddIn.Application.ActiveCell”
   we can get the current active Excel cell. We store the result in an Excel range and now using the range, value and color we can set our own text and colors to the active Excel Cell.

2.  Add Image: using
the Open File Dialog we can select our own image that needs to be added to the Excel file. Using the Excel.Shape we can add our selected image to the Excel file.

Search and bind Db Data to Excel: Now
we can create our own Custom Search control to be used in Excel to search our data from the database and bind the result to the Excel file.
Creating the table

In the button search click event we search for the data from the database and bind the result to an Excel cell using “Globals.ThisAddIn.Application.ActiveSheet.Cells”.
This will add the result to the active Excel sheet.

Step 4

Now we have created our own User Control to be added to our Excel Add-Ins. To add this user control to our Excel Add-In as we have already seen that the Excel Addin class “ThisAddIn.Cs” has start and stop events. Using
the Office “CustomTaskpane” we can add our user control to Excel as an Add-In as in the following.

Step 5

Step 1

Create a new project and select Office 2007 Word AddIn as in the following Image. Select your Project Folder and enter your Project Name.

Step 2

Add all your controls and design your user control depending on your requirements. By default in our Ribbon Control we can see a “RibbonGroup”. We can add all our controls to the Ribbon Group. Here
in my example I have changed the Group Label Text to “SHANU Add-In”. I have added three Ribbon Button Controls to the group. We can add an image to the Ribbon Button Controls and set the properties of the Button Control Size as “RibbobControlSizeLarge”. 

Step 4

Here we will add an image to Word. Using the Open File Dialog we can select our own image to be added to the Word file. Using the “Globals.ThisAddIn.Application.ActiveDocument.Shapes.AddPicture” method we can add our
selected image to the Word file.

Step 5

Here we will add a table to Word. Using the “Globals.ThisAddIn.Application.ActiveDocument.Tables” method we can add a table to the Word file. In my example I have created a table with 4 columns and 3 rows.

Step 6

Run your program and now you will see your own Ribbon Control has been added to the Word file as an Add-In.

You can download the source code from this link Source
Code Link

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 и пользуемся.

18 Sep How to Create an Excel VSTO Add-in

Howdee! For many years now, being an Excel expert has been almost synonymous with being an expert in writing VBA code. While VBA is a wonderful tool, in 2017 it is a bit dated in my opinion. So, today I want to introduce a new topic, the Excel VSTO add-in. This might be new to some of you, some of you might know what it means, and some may have even experimented with it before. VSTO stands for Visual Studio Tools for Office and is a means to use Microsoft’s Visual Studio IDE (Integrated Development Environment) to create and build your own Excel (and other Microsoft Office applications) add-ins. This has actually been around for several years now, but has yet to be widely adopted. I think this is a mistake by the Excel community.

Why use Visual Studio Tools for Office?

Building your applications using VSTO makes sense for a few reasons. First, Visual Studio is a much more advanced development environment than the VBA editor. Intellisense is much more robust which allows for faster coding and easier debugging. The advanced environment can be intimidating when you’re used to the more simple VBA development interface (it definitely was for me), but it is surprisingly easy to pick up.

Second, you can code in Visual Basic, C#, Python, and even JavaScript (although the base language must be C# or Visual Basic). These languages have significantly more recent support, both by Microsoft and the community at large, than does VBA. Developers are constantly building more libraries that you can use and, with C# in particular, the more popular ones are rarely deprecated. Parsing JSON for example, there are a couple of libraries in VBA to do this, but the support for them is often slow or nonexistent. The Newtonsoft JSON library from NuGet, on the other hand, is incredibly robust (and supports serialization along with parsing) and is actively supported.

Third, the ability to make modern looking interfaces with Winforms and WPF (Windows Presentation Foundation) makes your Excel applications look significantly more attractive than using VBA. Referencing a bit of reason number two here, there are dozens of libraries that extend the functionality of user interfaces and make it easier and faster to build beautiful Excel add-ins. I’ve used a couple of different libraries both professionally and personally and these really make the process fast, easy, and intuitive.

Finally, VSTO offers the ability to extend your Excel applications to the web. You can do this a couple of different ways. You can use task panes to bring the web into your desktop Excel applications, or you can use javascript and create add-ins that run in Excel online. That means you can easily make your add-in cross-platform by utilizing Excel online!

Creating your first Excel VSTO Add-in

Today, I want to just cover the basics of building an Excel VSTO application and I’ll get into some more detailed implementations in later posts. To start you’ll need to download Visual Studio. Any version 2010 or later will work, but I’ll be working with the 2017 community edition (the free version). You can download this here if you need to.

In the install options, I would recommend at least the following three items to get started: Universal Windows Platform development, .Net Desktop development, & Office/Sharepoint development.

With these three you should have plenty to get started developing your Excel add-ins. Once Visual Studio installs and you open it, you’ll see a start screen with a lot of different links on it. This is just the default start screen and you can pick up previous projects from here in the future. To get started with a new project, select “File” in the top left and then “New” and, finally, “Project”.

In the window that opens, select the language you wish to use (I’ll be using C# today). As I mentioned earlier, you must choose either Visual Basic or C# to start your app with, but you can use other languages later if desired. Next, select the Office/SharePoint section. In the center window, you’ll see several options underneath this language for the project template. You can create Web Add-in’s that can be used in Microsoft Online, a VSTO Add-in, or a VSTO template/workbook. Today we will go over the Excel VSTO Add-in, so let’s select that. Don’t forget to name it something useful at the bottom of the window.

Once you click OK, the project will take a minute to build as Visual Studio will go ahead and start the project for you including the code you’ll need to initialize the add-in. This will be contained in the “ThisAddin” file. It contains two methods that handle the startup and shutdown of the add-in so anything you need to do during those times should go inside those methods.

For today’s example, let’s build a simple add-in that will simply read out the address of our current cell and the contents it contains. This will give you a good grasp of how to begin interacting with the Excel object model from a VSTO project. One question you might have asked yourself already, is how can the user control when the code runs? A common approach with VBA code is to assign a macro to a button or some other object within the workbook.

Since we can’t do that in this example, the easiest way to let a user control running the code is to tie it to a ribbon control. To do that, right-click on the project name in the solution explorer. Select “Add” and “New Item”. A new window will pop up. The default selection should be “Ribbon (Visual Designer)” and that just happens to be the one we need. You can rename this ribbon also if you desire and then click “Add” in the bottom right.

Visual Studio will install the Ribbon to the project and open the designer file. If the “Toolbox” is not open on the left side of your screen, open it now by clicking on “View” in the top left and selecting “Toolbox”. Alternatively, you could press Ctrl+alt+X on the keyboard to do this. If you’re clicked on the ribbon designer, you should see “Office Ribbon Controls” as the first option in the toolbox. Inside this group, there is an option for button. Click and drag the button the ribbon interface and it should snap to “group 1” as a new button with the label “button1”.

As with VBA, we can rename these so they display something a little more appropriate by using the “Properties” window. This should appear in the bottom right of your Visual Studio window. Click on the group or button and change the names to something that makes sense to you. Below is a screen grab with the elements we just talked about called out (click to enlarge):

Now, we have our button in place, let’s get to writing some code! From the ribbon designer, you can double click the button to create an event handler just like you would in a VBA user form. The first thing we need to do is create a reference to the active cell so we can return some data about it. To do this, I’m actually going to jump over to the “ThisAddIn” file and enter some code there to demonstrate how to reference code between files in Visual Studio. Switch to the file and add the following code in the ThisAddIn class (if you’re using C#):

[cc lang=”csharp”]
public Excel.Range GetActiveCell()

{

return (Excel.Range)Application.ActiveCell;

}
[/cc]

Next, back in the method we created by double-clicking our button in the Ribbon class, let’s add the following code:

[cc lang=”csharp”]
private void ReadCellDataBtn_Click(object sender, RibbonControlEventArgs e)

{

Range thisCell = Globals.ThisAddIn.GetActiveCell();

MessageBox

.Show(“This cell’s address is: ” + thisCell.Address + ” — And it’s value is: ” + thisCell.Value);

}
[/cc]

If you just enter the code as I displayed above, you’ll get errors. You’ll need to make sure you add the proper using statements to the top of the Ribbon1 class. Those are using Microsoft.Office.Interop.Excel; and using System.Windows;

Once this is done – we can test the Excel VSTO add-in by pressing F5 on our keyboard or clicking “Start” at the top of Visual Studio. This will open an instance of Excel for us to test with. We can type some information into a blank spreadsheet and quickly test if our code works. Please note that you’ll need to add the “Add-ins” ribbon to Excel if you haven’t done so already. This is done by clicking “File”, then “Options”, and finally “Customize Ribbon”. As you can see below, this example is returning the value of our active cell to a message box.

This is all I wanted to cover in this article since, if you’re new to Excel VSTO Add-ins, your head might be hurting right now. Don’t worry, mine was as well when I first started playing with them. My best recommendation for becoming familiar with this approach is to pick a project you’ve done in VBA (the simpler the better) and try to replicate it as an Excel VSTO add-in. That was my first step and I had a lot of mistakes on the way. However, I think this should be the future of working with Microsoft Excel applications for reasons stated at the beginning of this article. Let me know your thoughts below in the comments.

Also, the example file will be available for download as usual if you’re a free member to my site. However, with this type of add-in I am going to zip the Visual Studio project file up and have it available for download. So, if you want to test it out you will need to download Visual Studio before you’re able to. Feel free to drop a question in the comments if you have an issue doing this.

Cheers,

R