Wdrażanie niestandardowego procesora dyrektywy

Aby użyć niestandardowego procesora dyrektywy w Visual Studio na dowolnym komputerze, musisz go zarejestrować za pomocą jednej z metod opisanych w tym temacie.

Alternatywne metody to:

• Rozszerzenie Visual Studio (VSIX).Zapewnia to sposób zainstalowania i odinstalowywania procesora dyrektywy zarówno na swoim komputerze, jak i na innych komputerach.Zazwyczaj można umieścić inne funkcje w tym samym VSIX.

• VSPackage.W przypadku definiowania VSPackage, zawierającego inne funkcje oprócz procesora dyrektywy, istnieje wygodna metoda rejestracji procesora dyrektywy.

• Ustaw klucz rejestru.W tej metodzie należy dodać wpis rejestru dla procesora dyrektywy.

Należy użyć jednej z następujących metod tylko wtedy, gdy chcesz przekształcić szablon tekstowy w Visual Studio lub MSBuild.Jeśli używasz niestandardowego hosta w aplikacji, niestandardowy host jest odpowiedzialny za znalezienie procesorów dyrektyw dla każdej dyrektywy.

Wdrażanie procesora dyrektywy w VSIX

Można dodać niestandardowy procesor dyrektywy do Rozszerzenia Visual Studio (VSIX).

Upewnij się, że w pliku .vsix znajdują się dwa następujące elementy:

• Zestaw (.dll), który zawiera niestandardową klasę procesora dyrektywy.

• Plik .pkgdef, który rejestruje procesor dyrektywy.Główna nazwa pliku musi być zgodna z nazwą zestawu.Na przykład, pliki mogą być nazwane CDP.dll i CDP.pkgdef.

Aby sprawdzić lub zmienić zawartość pliku .vsix, zmień rozszerzenie nazwy pliku na .zip, a następnie otwórz go.Po zakończeniu edycji zawartości zmień nazwę pliku z powrotem na .vsix.

Istnieje kilka sposobów tworzenia plików .vsix.Poniższa procedura opisuje jedną z metod.

Aby opracować niestandardowy procesor dyrektywy w projekcie VSIX

1. Utwórz projekt VSIX w Visual Studio.

   • W oknie dialogowym Nowy projekt rozwiń Visual Basic lub Visual C#, a następnie rozwiń Rozszerzalność.Kliknij Projekt VSIX.

2. W source.extension.vsixmanifest ustaw typ zawartości i obsługiwane wersje.

   1. W edytorze manifestu VSIX, na karcie Zasoby wybierz Nowy i ustaw właściwości nowego elementu:

      Typ zawartości = VSPackage

      Projekt źródłowy = <the current project>

   2. Kliknij Wybrane wersje i sprawdź typy instalacji, dla których chcesz mieć działający procesor dyrektywy.

3. Dodaj plik .pkgdef i ustaw jego właściwości, które mają zostać uwzględnione w VSIX.

   1. Utwórz plik tekstowy i nadaj mu nazwę <assemblyName>.pkgdef.

      Nazwa <assemblyName> jest zwykle taka sama, jak nazwa projektu.

   2. Wybierz go w oknie Eksploratora rozwiązań i ustaw jego właściwości w następujący sposób:

      Akcja kompilacji = Zawartość

      Kopiuj do katalogu wyjściowego = Zawsze kopiuj

      Uwzględnione w VSIX = Prawda

   3. Ustaw nazwę VSIX i upewnij się, że identyfikator jest unikatowy.

4. Dodaj następujący tekst do pliku .pkgdef.

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

   Zastąp następujące nazwy własnymi nazwami: CustomDirectiveProcessorName, NamespaceName, ClassName, AssemblyName.

5. Dodaj następujące odwołania do projektu:

   • Microsoft.VisualStudio.TextTemplating.*.0

   • Microsoft.VisualStudio.TextTemplating.Interfaces.*.0

   • Microsoft.VisualStudio.TextTemplating.VSHost.*.0

6. Dodaj niestandardową klasę procesora dyrektywy do projektu.

   To jest klasa publiczna, która powinna implementować DirectiveProcessor lub RequiresProvidesDirectiveProcessor.

Aby zainstalować procesor dyrektywy niestandardowej

1. W Eksploratorze Windows (Eksplorator plików w systemie Windows 8) otwórz katalog kompilacji (zazwyczaj bin\Debug lub bin\Release).

2. Jeśli chcesz zainstalować procesor dyrektywy na innym komputerze, skopiuj plik .vsix do innego komputera.

3. Kliknij dwukrotnie plik .vsix.Zostanie wyświetlony Instalator rozszerzenia Visual Studio.

4. Uruchom ponownie Visual Studio.Teraz można uruchomić szablony tekstowe, które zawierają dyrektywy odwołujące się do procesora dyrektywy niestandardowej.Każda dyrektywa jest tej postaci:

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

Aby odinstalować lub tymczasowo wyłączyć procesor dyrektywy niestandardowej

1. W menu Visual Studio Narzędzia kliknij Menedżer rozszerzeń.

2. Wybierz VSIX zawierający procesor dyrektywy, a następnie kliknij przycisk Odinstaluj lub Wyłącz.

Rozwiązywanie problemów z procesorem dyrektywy w VSIX

Jeśli procesor dyrektywy nie działa, poniższe sugestie mogą pomóc:

• Nazwa procesora, którą określasz w dyrektywie niestandardowej, powinna odpowiadać nazwie CustomDirectiveProcessorName, która została podana w pliku .pkgdef.

• Metoda IsDirectiveSupported musi zwracać true, kiedy jest do niej przekazywana nazwa CustomDirective.

• Jeśli nie widzisz rozszerzenia w Menedżerze rozszerzeń, ale system nie pozwoli na jego instalację, usuń rozszerzenie z %localappdata%\Microsoft\VisualStudio\*.0\Extensions\.

• Otwórz plik .vsix i sprawdź jego zawartość.Aby go otworzyć, zmień rozszerzenie nazwy pliku na .zip.Sprawdź, czy zawiera on pliki .dll, .pkgdef i extension.vsixmanifest.Plik extension.vsixmanifest powinien zawierać odpowiednią listę w węźle SupportedProducts i powinien też zawierać węzeł VsPackage w węźle Content:

  <Content>

  <VsPackage>CustomDirectiveProcessor.dll</VsPackage>

  </Content>

Wdrażanie procesora dyrektywy w VSPackage

Jeśli procesor dyrektywy jest częścią pakietu VSPackage, który zostanie zainstalowany w pamięci podręcznej GAC, system może automatycznie wygenerować plik .pkgdef.

Umieść następujący atrybut w klasie pakietu:

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

[!UWAGA]

Ten atrybut jest umieszczany w klasie pakietu, a nie w klasie procesora dyrektywy.

Plik .pkgdef zostanie wygenerowany podczas tworzenia projektu.Podczas instalowania pakietu VSPackage plik .pkgdef zarejestruje procesor dyrektywy.

Sprawdź, czy plik .pkgdef pojawia się w folderze kompilacji, zwykle bin\Debug lub bin\Release.Jeśli się nie pojawia, otwórz plik .csproj w edytorze tekstu i usuń następujący węzeł: <GeneratePkgDefFile>false</GeneratePkgDefFile>.

Aby uzyskać więcej informacji, zobacz VSPackages.

Ustawianie klucza rejestru.

Ta metoda instalacji procesora dyrektywy niestandardowej jest najmniej polecana.Nie zapewnia wygodnego sposobu włączania i wyłączania procesora dyrektywy i nie zapewnia metody dystrybucji procesora dyrektywy do innych użytkowników.

Przestroga
Niepoprawne edytowanie rejestru może spowodować poważne uszkodzenie systemu.Przed wprowadzeniem zmian w rejestrze należy wykonać kopię zapasową wszystkich cennych danych, które znajdują się na komputerze.

Aby zarejestrować procesor dyrektywy przez ustawienie klucza rejestru

1. Uruchom regedit.

2. W edytorze regedit przejdź do

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\*.0\TextTemplating\DirectiveProcessors

   Jeśli chcesz zainstalować procesor dyrektywy w wersji doświadczalnej Visual Studio, wstaw „Exp” po „11.0”.

3. Dodaj klucz rejestru, który ma taką samą nazwę jak klasa procesora dyrektywy.

   • W drzewie rejestru kliknij prawym przyciskiem myszy węzeł DirectiveProcessors, wskaż Nowy, a następnie kliknij Klucz.

4. W nowym węźle dodaj wartości ciągu dla Class i CodeBase lub Assembly, zgodnie z poniższymi tabelami.

   1. Kliknij prawym przyciskiem myszy węzeł, który został utworzony, wskaż Nowy, a następnie kliknij Wartość ciągu.

   2. Wyedytuj nazwę wartości.

   3. Kliknij dwukrotnie nazwę i wyedytuj dane.

Jeśli procesor dyrektywy niestandardowej nie znajduje się w pamięci podręcznej GAC, podklucze rejestru powinny wyglądać tak, jak w poniższej tabeli:

Name	Typ	Dane
(Domyślnie)	REG_SZ	(wartość nieustawiona)
Class	REG_SZ	<Nazwa przestrzeni nazw>.<Nazwa klasy>
CodeBase	REG_SZ	<Twoja ścieżka>\<Twoja nazwa zestawu>

W przypadku zestawu w pamięci podręcznej GAC, podklucze rejestru powinny wyglądać tak, jak w poniższej tabeli:

Name	Typ	Dane
(Domyślnie)	REG_SZ	(wartość nieustawiona)
Class	REG_SZ	<Twoja w pełni kwalifikowana nazwa klasy>
Zestaw	REG_SZ	<Twoja nazwa zestawu w GAC>

Zobacz też

Koncepcje

Tworzenie niestandardowych procesorów dyrektywy T4 dotyczącej szablonu tekstowego