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

Развертывание пользовательского обработчика директив

  • Статья

Для использования пользовательского процессора директив в Visual Studio на любом компьютере необходимо зарегистрировать его одним из описанных в этом разделе способов.

Альтернативные методы таковы:

  • Расширение Visual Studio (VSIX). Предоставляет способ установки и удаления процессора директив на вашем и других компьютерах. Обычно можно упаковывать другие функции в тот же VSIX.

  • VSPackage. Вы определяете VSPackage, содержащий помимо процессора директив и другие функции; это удобный метод регистрации процессора директив.

  • Определить раздел реестра. При использовании данного метода вы добавляете для процессора директив раздел реестра.

Эти методы необходимо использовать только в том случае, если требуется преобразовать текстовый шаблон в Visual Studio или MSBuild. Если используется в вашем собственном приложении, это пользовательское основное приложение отвечает за поиск процессора директив для каждой директивы.

Развертывание процессора директив в VSIX

Пользовательский процессор директив можно добавить в Расширение Visual Studio (VSIX).

Необходимо убедиться, что следующие два элемента содержатся в файле с расширением vsix:

  • Сборка (dll), содержащая класс пользовательского процессора директив.

  • Файл pkgdef, регистрирующий процессор директив. Корневое имя файла сборки должно совпадать с именем сборки. Например, файлы могут называться CDP.dll и CDP.pkgdef.

Чтобы просмотреть или изменить содержимое файла vsix, измените расширение его имени на zip и откройте этот файл. После изменения содержимого снова поменяйте расширение имени файла на vsix.

Файл vsix можно создать несколькими способами. Следующая процедура представляет один из них.

Разработка пользовательского процессора директив в проекте VSIX

  1. Создайте проект VSIX в Visual Studio.

    • В диалоговом окне Новый проект разверните узел Visual Basic или Visual C#, а затем узел Расширение среды. Щелкните Проект VSIX.

  2. В source.extension.vsixmanifest задайте тип содержимого и поддерживаемые выпуски.

    1. В редакторе манифеста VSIX щелкните Добавление содержимого и задайте его свойства таким образом:

      Тип контента = VSPackage

      Исходный проект = <текущий проект>

    2. Щелкните Выбранные выпуски и отметьте типы установки, с которыми должно быть возможно использовать данный процессор директив.

  3. Добавьте файл pkgdef и установит его свойства для включения в VSIX.

    1. Создайте текстовый файл и назовите его <имяСборки>.pkgdef.

      Как правило, <имяСборки> совпадает с именем проекта.

    2. Выберите его в обозревателе решений и задайте его свойства следующим образом:

      Действие построения = Содержимое

      Копировать в выходной каталог = Всегда копировать

      Включить в VSIX = Истина

    3. Задайте имя VSIX и убедитесь, что этот идентификатор уникален.

  4. Добавьте в pkgdef-файл следующий текст:

    [$RootKey$\TextTemplating]
[$RootKey$\TextTemplating\DirectiveProcessors]
[$RootKey$\TextTemplating\DirectiveProcessors\ CustomDirectiveProcessorName]
@="Custom Directive Processor description"
"Class"="NamespaceName.ClassName"
"CodeBase"="$PackageFolder$\AssemblyName.dll"

    Замените следующие имена собственными именами: CustomDirectiveProcessorName, NamespaceName, ClassName, AssemblyName.

  5. В проекте добавьте ссылки на следующее:

    • Microsoft.VisualStudio.TextTemplating.10.0

    • Microsoft.VisualStudio.TextTemplating.Interfaces.10.0

    • Microsoft.VisualStudio.TextTemplating.VSHost.10.0

  6. Добавьте в проект класс вашего пользовательского процессора директив.

    Это открытый класс, который должен реализовывать тип DirectiveProcessor или RequiresProvidesDirectiveProcessor.

Установка пользовательского процессора директив

  1. В Проводнике Windows откройте каталог построения (обычно это bin\Debug или bin\Release).

  2. Если требуется установить процессор директив на другой компьютер, скопируйте vsix-файл на другой компьютер.

  3. Дважды щелкните vsix-файл. Откроется окно установщика расширений Visual Studio.

  4. Перезапустите Visual Studio. Теперь вы сможете запускать текстовые шаблоны, содержащие директивы со ссылками на ваш пользовательский процессор директив. Каждая директива имеет следующую форму:

    <#@ CustomDirective Processor="CustomDirectiveProcessorName" parameter1="value1" … #>

Удаление или временное отключение пользовательского процессора директив

  1. В Visual Studio выберите в меню Сервис команду Диспетчер расширений.

  2. Выберите VSIX, содержащий процессор директив, и щелкните Удалить или Отключить.

Устранение неполадок процессора директив в VSIX

Если процессор директив не работает, этому могут быть следующие причины:

  • Имя процессора, заданное в пользовательской директиве, должно соответствовать значению CustomDirectiveProcessorName, заданному в pkgdef-файле.

  • Метод IsDirectiveSupported должен возвращать значение true, когда ему передается имя CustomDirective.

  • Если вы не видите расширение в диспетчере расширений, но система не позволяет его установить, удалите это расширение из %localappdata%\Microsoft\VisualStudio\10.0\Extensions\.

  • Откройте vsix-файл и проверьте его содержимое. Чтобы его открыть, смените расширение имени файла на zip. Убедитесь, что он содержит файлы с расширениями dll, pkgdef и файл extension.vsixmanifest. Файл extension.vsixmanifest должен содержать соответствующий список в узле SupportedProducts, а также содержать узел VsPackage, расположенный в иерархии ниже узла Content.

    <Content>

    <VsPackage>CustomDirectiveProcessor.dll</VsPackage>

    </Content>

Развертывание процессора директив в VSPackage

Если процессор директив является частью VSPackage, который будет установлен в глобальный кэш сборок, можно сделать так, чтобы система сама сгенерировала pkgdef-файл.

Поместите в класс пакета следующий атрибут.

[ProvideDirectiveProcessor(typeof(DirectiveProcessorClass), "DirectiveProcessorName", "Directive processor description.")]

Примечание

Этот атрибут следует поместить в класс пакета, не в класс процессора директив.

Файл pkgdef будет автоматически создан во время построения проекта. При установке VSPackage pkgdef-файл будет регистрировать процессор директив.

Убедитесь, что pkgdef-файл содержится в папке построения, которой обычно является bin\Debug или bin\Release. Если там нет этого файла, откройте CSPROJ-файл в текстовом редакторе и удалите следующий узел: <GeneratePkgDefFile>false</GeneratePkgDefFile>.

Дополнительные сведения см. в разделе VSPackages.

Создание раздела реестра

Данный способ установки пользовательского процессора директив рекомендуется использовать в последнюю очередь. Он не предусматривает удобного способа включения и отключения процессора директив и способа передачи процессора директив другим пользователям.

Предупреждение

Неправильное изменение реестра может привести к серьезному повреждению системы.Перед внесением изменений в реестр необходимо выполнить резервное копирование всех ценных данных на компьютере.

Регистрация процессора директив путем создания раздела реестра

  1. Запустите программу regedit из меню "Пуск" Windows.

  2. В программе regedit перейдите следующему разделу:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\10.0\TextTemplating\DirectiveProcessors

    Если нужно установить процессор директив в экспериментальной версии Visual Studio, после "10.0" вставьте "Exp".

  3. Добавьте раздел реестра с именем, совпадающим с именем класса процессора директив.

    • В дереве реестра щелкните правой кнопкой мыши узел DirectiveProcessors, выберите команду Создать, а затем Раздел.

  4. Добавьте в новый узел строковые значения для параметров Class и CodeBase либо Assembly согласно указаниям, приведенным в следующих таблицах.

    1. Щелкните правой кнопкой мыши созданный узел, выберите команду Создать, а затем Строковый параметр.

    2. Отредактируйте имя значения.

    3. Дважды щелкните имя и отредактируйте данные.

Если пользовательский процессор директив не находится в глобальном кэше сборок, подраздел реестра должен выглядеть, как в следующей таблице:

Имя

Тип

Данные

(Значение по умолчанию)

REG_SZ

(значение не задано)

Класс

REG_SZ

<Имя пространства имен>.<Имя класса>

CodeBase

REG_SZ

<Ваш путь>\<Ваше имя сборки>

Если сборка находится в глобальном кэше сборок, подраздел реестра должен выглядеть, как в следующей таблице:

Имя

Тип

Данные

(Значение по умолчанию)

REG_SZ

(значение не задано)

Класс

REG_SZ

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

Сборка

REG_SZ

<Имя сборки в глобальном кэше сборок>

См. также

Основные понятия

Создание пользовательских обработчиков директив для текстовых шаблонов