Регистрация надстройки

Статья
02/20/2013

После создания надстройки ее необходимо зарегистрировать в Visual Studio, прежде чем ее можно будет активировать, используя Диспетчер надстроек.Для этого используется XML-файл с расширением имени файла ADDIN.

Этот файл с расширением ADDIN содержит описание сведений, необходимых Visual Studio для отображения надстройки в окне Диспетчер надстроек.При запуске Visual Studio выполняется поиск расположения файлов с расширением ADDIN на предмет доступных файлов с расширением ADDIN.В случае нахождения такого файла XML-файл считывается, и для окна Диспетчер надстроек передаются сведения, необходимые для запуска надстройки по щелчку мыши.

Файл с расширением ADDIN создается автоматически вместе с надстройкой мастером надстроек.Также файл с расширением ADDIN можно создать вручную с помощью сведений, представленных в этом разделе.

Расположение файлов

Мастер надстроек автоматически создает две копии файла с расширением ADDIN следующим образом.

Расположение файла с расширением ADDIN	Расположение DLL-файла	Описание
Корневая папка проекта \Documents\Visual Studio 2010\Projects\MyAddin1\MyAddin1\	Локальный путь (MyAddin1.dll)	Используется для развертывания проекта надстройки.Включается в проект для простоты редактирования и имеет локальный путь для развертывания в стиле XCopy.
Папка надстройки \Documents\Visual Studio 2010\Addins\ -или- расположение_общих_документов\Addins\	Папка отладки проекта (Например, \Documents\Visual Studio 2010 Projects\MyAddin1\MyAddin1\bin\)	Используется для запуска надстройки в среде отладки.Должна всегда указывать на выходной путь текущей конфигурации построения.

Корневая папка проекта

\Documents\Visual Studio 2010\Projects\MyAddin1\MyAddin1\

Локальный путь (MyAddin1.dll)

Используется для развертывания проекта надстройки.Включается в проект для простоты редактирования и имеет локальный путь для развертывания в стиле XCopy.

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

\Documents\Visual Studio 2010\Addins\

-или-

расположение_общих_документов\Addins\

Папка отладки проекта

(Например, \Documents\Visual Studio 2010

Projects\MyAddin1\MyAddin1\bin\)

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

Чтобы установить надстройку на другой компьютер, файл с расширением ADDIN необходимо поместить в расположение, в котором Visual Studio проверяет наличие надстроек.Эти расположения перечислены в диалоговом окне Параметры в узле Среда на странице Безопасность надстроек.Дополнительные сведения см. в разделе Безопасность надстроек.

DLL-файл, содержащий надстройку, можно установить в любом месте на клиентском компьютере.Однако рекомендуется поместить его вместе с файлом с расширением ADDIN.

Примечание
Элемент <Assembly> файла с расширением ADDIN должен указывать на DLL-файл, содержащий двоичные файлы для надстройки.

Файл ADDIN

XML-файл с расширением ADDIN разбит на следующие разделы с тегами.

Раздел	Описание
Ведущее приложение	(Обязательный). Указывает имена и номера версий приложений, которые могут загрузить надстройку.
Надстройка	(Обязательный). Содержит элементы, описывающие надстройку.
Страница "Сервис Параметры"	(Необязательный). Указывает страницу в диалоговом окне Параметры, на которой можно настроить надстройку.Дочерние узлы указывают категорию и подкатегорию страницы Параметры, а также ее имя сборки и полное имя класса.

Следующие элементы являются дочерними для раздела <Addin>.

Элемент	Описание
Сведения в окне “О программе”	(Необязательный). Указывает текст, который будет отображаться для надстройки в диалоговом окне О программе в Visual Studio.
Данные значка окна “О программе”	(Необязательный). Содержит двоичные данные значка, который будет отображаться для надстройки в диалоговом окне О программе в Visual Studio.
Расположение значка	(Необязательный). Указывает абсолютный или относительный путь к значку, который будет отображаться для надстройки в диалоговом окне О программе в Visual Studio.
Сборка	(Обязательный). Указывает расположение двоичных данных надстройки.В этом поле можно указать локальный путь, сетевой путь или URL-адрес.
Безопасность командной строки	(Необязательный). Указывает режимы Visual Studio, с которыми совместима надстройка, например только командная строка, только интегрированная среда разработки или и то, и другое.
Предварительная загрузка команды	(Необязательный). Указывает предварительно загруженное состояние надстройки, то есть, должна ли надстройка создавать пользовательский интерфейс при помощи метода, такого как Commands.AddNamedCommand.
Полное имя класса	(Обязательный). Указывает имя класса, используемого для подключения к надстройке.
Поведение загрузки	(Необязательный) Определяет, будет ли надстройка загружаться при запуске или вручную.

Ниже приводятся подробные сведения о каждой из настроек.Дополнительные сведения о расположении многих описанных элементов в иерархии см. в разделе "Пример XML-файла ADDIN" далее в этом разделе.

Ведущее приложение

Элемент <Name> секции Host Application содержит имя приложения.Это имя, отображаемое в заголовке окна приложения или возвращаемое DTE.Name.Например, для Visual Studio тег будет содержать "Microsoft Visual Studio", а для интегрированной среды разработки макросов в теге будет указано "Microsoft Visual Studio Macros".

В одном файле с расширением ADDIN может быть несколько значений ведущего приложения.Каждое значение должно быть заключено в теги <Name> в элементе <HostApplication>.Помимо элемента <Name>, каждый элемент <HostApplication> должен также содержать номер версии приложения, заключенного в теги <Version>.Например:

   <HostApplication>
      <!-- First Host App name (required). -->
      <Name>Microsoft Visual Studio</Name>
      <Version>10.0</Version>
   </HostApplication>
   <HostApplication>
      <!-- An additional supported program/version. -->
      <Name>Microsoft Visual Studio Macros</Name>
      <Version>10.0</Version>
   </HostApplication>

Для представления <Version> для любой версии Visual Studio можно также указывать символ звездочки (*).

Понятное имя

Элемент <FriendlyName>, расположенный в элементе <Addin>, указывает строку, которая будет отображаться в столбце Имеющиеся надстройки в окне Диспетчер надстроек.Например:

   <FriendlyName>My New Super Addin</FriendlyName>

Описание

Элемент <Description>, расположенный в элементе <Addin>, указывает строку, которая будет отображаться в диалоговом окне Описание в окне Диспетчер надстроек.Например:

   <Description>This add-in will change your life!</Description>

Сведения в окне “О программе”

Если во время создания надстройки был выбран параметр для создания настроек диалогового окна О программе, этот элемент будет добавлен к файлу с расширением ADDIN.Этот элемент указывает текст, который будет отображаться в диалоговом окне О программе в Visual Studio.Например:

   <AboutBoxDetails>For add-in support, call 1-800-xxx-
     xxxx.</AboutBoxDetails>

Данные значка окна “О программе”

Если во время создания надстройки был выбран параметр для создания настроек диалогового окна О программе, этот элемент будет добавлен к файлу с расширением ADDIN.Этот элемент содержит двоичные данные, указывающие значок, который будет отображаться в диалоговом окне О программе в Visual Studio.Например:

<AboutIconData>0000010006 . . . FFFF0000</AboutIconData>

Сборка

Элемент <Assembly>, расположенный в элементе <Addin>, указывает расположение двоичных файлов надстройки.В этом элементе можно указать относительный путь, абсолютный путь ("file"), зарегистрированное имя сборки ("assembly") или допустимый URL-адрес ("url").

В следующем примере показан абсолютный путь к расположению.В этом случае параметру src присвоено значение file для указания расположения библиотеки DLL надстройки.
```
<Assembly src="file">C:\Documents and Settings\jdoe\Application Data\Microsoft\Visual Studio\10.0\AddIns\MyAddin4.dll</Assembly>
```
В следующем примере показано зарегистрированное расположение.В этом случае параметру src присвоено значение assembly для указания зарегистрированной библиотеки DLL надстройки.
```
<Assembly src="assembly">BookshelfDefineAddin</Assembly>
```
В следующем примере показан URL-адрес расположения.В этом случае параметр src имеет значение url, указывая расположение библиотеки DLL надстройки в Интернете.
```
<Assembly src="url">http://somewebsite.com/MyAddin4.dll</Assembly>
```

Полное имя класса

Элемент <FullClassName> указывает полное имя класса, используемого для подключения к надстройке.Он включает пространство имен, содержащее класс.Например:

    <FullClassName>MyAddin4.Connect</FullClassName>

Поведение загрузки

Элемент <LoadBehavior> определяет, будет ли надстройка загружаться автоматически при запуске интегрированной среды разработки или вручную.Элемент <LoadBehavior> содержится в элементе <Addin>.Например:

    <LoadBehavior>1</LoadBehavior>

Несмотря на то, что элемент <LoadBehavior> не является обязательным, его рекомендуется использовать для явного определения типа загрузки надстройки.

Значение	Описание
0	Надстройка не загружается при запуске интегрированной среды разработки и должна быть запущена вручную.
1	Надстройка загружается автоматически при запуске интегрированной среды разработки.
4	Надстройка загружается, когда devenv запускается из командной строки с помощью коммутатора построения (devenv /build).

Предварительная загрузка команды

Элемент <CommandPreload> указывает, требуется ли предварительная загрузка надстройки.При предварительной загрузке надстройка загружается при первом запуске Visual Studio после установки файла с расширением ADDIN.Например:

    <CommandPreload>1</CommandPreload>

Этот элемент позволяет задать загрузку надстройки после запуска Visual Studio.Такой режим позволяет надстройке создать необходимые элементы пользовательского интерфейса, такие как кнопки панели команд, или выполнить другие задачи инициализации (впервые), например создание параметров надстройки по умолчанию.Затем надстройка выгружается, пока пользователь не выполнит одну из команд, созданных надстройкой.Таким образом, надстройка загружается, как это необходимо.

Значение	Описание
0	Надстройка не будет загружена до тех пор, пока пользователь не запустит ее, используя Диспетчер надстроек, или если не будет задана загрузка надстройки в момент запуска.
1	Надстройка загружается автоматически при запуске Visual Studio впервые после установки файла с расширением ADDIN.

Можно проверить реализуемый метод OnConnection, чтобы убедиться, что тип подключения, заданный во втором аргументе OnConnection, является ext_cm_UISetup.Если это так, команды можно размещать как угодно с помощью метода AddNamedCommand или метода AddControl.

Безопасность командной строки

Необязательный элемент <CommandLineSafe> указывает, должна ли надстройка отключать пользовательский интерфейс при запуске в командной строке, например при выполнении операций построения из командной строки или подобных операций.(Для этого необходимо выбрать параметр Персональная надстройка никогда не будет создавать модальный пользовательский интерфейс в окне Мастер надстроек.) Он также указывает режимы Visual Studio, с которыми совместима надстройка, например только командная строка или только интегрированная среда разработки.Например:

    <CommandLineSafe>0</CommandLineSafe>

Значение	Описание
0	Указывает, что надстройка не является безопасной для командной строки и может отображать пользовательский интерфейс.
1	Указывает, что надстройка является безопасной для командной строки и не отображает пользовательский интерфейс.

Страница "Сервис Параметры"

Необязательный элемент <ToolsOptionsPage> указывает страницу Параметры, чтобы пользователи могли настроить надстройку.Дочерние узлы указывают категорию и подкатегорию, на которых отображается страница, имя сборки и полное имя класса страницы Параметры.В следующем примере показа иерархия этого элемента.

  <ToolsOptionsPage>
    <Category Name="Text Editor">
      <SubCategory Name="General">
        <Assembly>"MyFilePath\MyAddInOptionPage.dll"</Assembly>
        <FullClassName>"MyNamespace.MyAddInOptionPage"</FullClassName>
      </SubCategory>
    </Category>
  </ToolsOptionsPage>

Пример XML-файла ADDIN

В следующем примере представлен XML-файл ADDIN целиком.В нем показана иерархия элементов, описанных в данном разделе.

<?xml version="1.0" encoding="UTF-16" standalone="no"?>
<Extensibility 
  xmlns="https://schemas.microsoft.com/AutomationExtensibility">
    <HostApplication>
        <Name>Microsoft Visual Studio Macros</Name>
        <Version>10.0</Version>
    </HostApplication> 
    <HostApplication>
        <Name>Microsoft Visual Studio</Name>
        <Version>10.0</Version>
    </HostApplication>
    <Addin>
        <FriendlyName>My great new add-in.</FriendlyName>
        <Description>This add-in does it all.</Description>
        <AboutBoxDetails>Copyright 2010.</AboutBoxDetails>
        <AboutIconData>0000 . . . FFFF0000</AboutIconData>
        <Assembly>MyNewAddin.dll</Assembly>
        <FullClassName>MyNewAddin.Connect</FullClassName>
        <LoadBehavior>1</LoadBehavior>
        <CommandPreload>1</CommandPreload>
        <CommandLineSafe>0</CommandLineSafe>
    </Addin>
</Extensibility>

См. также

Поделиться через