Distribuzione di un processore di direttiva personalizzato

Articolo
08/11/2011

Per utilizzare un processore di direttiva personalizzato in Visual Studio in un computer qualsiasi, è necessario registrarlo da uno dei metodi descritti in questo argomento.

I metodi alternativi sono i seguenti:

Visual Studio Extension (VSIX). Fornisce un modo per installare e disinstallare il processore di direttiva sia in un proprio computer che in altri computer. In genere, è possibile comprimere altre funzionalità nello stesso VSIX.
Package VS. Se si definisce un package VS che contiene altre funzionalità oltre al processore di direttiva, esiste un metodo comodo per registrare il processore di direttiva.
Impostare una chiave del Registro di sistema. In questo metodo, si aggiunge una voce del Registro di sistema per il processore di direttiva.

È necessario utilizzare uno di questi metodi solo se si desidera trasformare il modello di testo in Visual Studio o MSBuild. Se si utilizza un host personalizzato nella propria applicazione, l'host personalizzato è responsabile dell'individuazione dei processori di direttive per ciascuna direttiva.

Distribuzione di un processore di direttiva in un pacchetto VSIX

È possibile aggiungere un processore di direttiva personalizzato a un pacchetto Visual Studio Extension (VSIX).

È necessario assicurarsi che i due elementi seguenti siano contenuti nel file .vsix:

L'assembly (.dll) che contiene la classe del processore di direttiva personalizzata.
Un file .pkgdef che registra il processore di direttiva. Il nome radice del file deve essere uguale all'assembly. Ad esempio, i file potrebbero essere denominati CDP.dll e CDP.pkgdef.

Per esaminare o modificare il contenuto di un file .vsix, cambiare l'estensione del file in .zip, quindi aprirlo. Dopo avere modificato il contenuto, reimpostare l'estensione del file su .vsix.

Esistono diversi modi di creare un file .vsix. Nella procedura seguente ne viene descritto uno.

Per sviluppare un processore di direttiva personalizzato in un progetto VSIX

Creare un progetto VSIX in Visual Studio.
- Nella finestra di dialogo Nuovo progetto espandere il nodo Visual Basic o Visual C#, quindi espandere Extensibility. Fare clic su Progetto VSIX.
In source.extension.vsixmanifest impostare il tipo di contenuto e le edizioni supportate.
1. Nell'editor del manifesto VSIX fare clic su Aggiungi contenuto e impostare le relative proprietà come segue:
  
  Tipo di contenuto = Package VS
  
  Progetto di origine = <progetto corrente>
2. Fare clic su Edizioni selezionate e controllare i tipi di installazione nei quali si desidera che il processore di direttiva sia utilizzabile.
Aggiungere un file .pkgdef e impostarne le proprietà da includere in VSIX.
1. Creare un file di testo e denominarlo <nomeAssembly>.pkgdef.
  
  <nomeAssembly> corrisponde in genere allo stesso nome del progetto.
2. Selezionarlo in Esplora soluzioni e impostarne le proprietà come segue:
  
  Operazione di compilazione = Contenuto
  
  Copia nella directory di output = Copia sempre
  
  Includi in VSIX = True
3. Impostare il nome del pacchetto VSIX e assicurarsi che l'ID sia univoco.

Aggiungere il seguente testo al file .pkgdef.

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

Sostituire i nomi seguenti con i propri nomi: CustomDirectiveProcessorName, NamespaceName, ClassName, AssemblyName.

Aggiungere i riferimenti seguenti al progetto:
- Microsoft.VisualStudio.TextTemplating.10.0
- Microsoft.VisualStudio.TextTemplating.Interfaces.10.0
- Microsoft.VisualStudio.TextTemplating.VSHost.10.0
Aggiungere la classe del processore di direttiva personalizzato al progetto.

Si tratta di una classe pubblica che deve implementare DirectiveProcessor o RequiresProvidesDirectiveProcessor.

Per installare il processore di direttiva personalizzato

In Esplora risorse aprire la directory di compilazione, in genere bin\Debug o bin\Release.
Se si desidera installare il processore di direttiva in un altro computer, copiare il file .vsix nell'altro computer.
Fare doppio clic sul file .vsix. Verrà visualizzato Visual Studio Extension Installer.
Riavviare Visual Studio. Si sarà ora in grado di eseguire modelli di testo che contengono direttive che si riferiscono al processore di direttiva personalizzato. Ogni direttiva è nel seguente formato:

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

Per disinstallare o disabilitare temporaneamente il processore di direttiva personalizzato

In Visual Studio, nel menu Strumenti fare clic su Gestione estensioni.
Selezionare il pacchetto VSIX che contiene il processore di direttiva, quindi fare clic su Disinstalla o Disabilita.

Risoluzione dei problemi relativi a un processore di direttiva in un pacchetto VSIX

Se il processore di direttiva non funziona, è possibile seguire i suggerimenti indicati di seguito:

Il nome del processore che si specifica nella direttiva personalizzata deve corrispondere al CustomDirectiveProcessorName specificato nel file .pkgdef.
Il metodo IsDirectiveSupported deve restituire true quando viene passato il nome di CustomDirective.
Se l'estensione non è visibile in Gestione estensioni, ma il sistema non consente di installarla, eliminare l'estensione da %localappdata%\Microsoft\VisualStudio\10.0\Extensions\.
Aprire il file .vsix ed esaminarne il contenuto. Per aprirlo, impostare l'estensione del file su .zip. Verificare che contenga i file .dll, .pkgdef ed extension.vsixmanifest. Il file extension.vsixmanifest deve contenere l'elenco adatto nel nodo SupportedProducts e deve contenere anche un nodo Package VS sotto il nodo Contenuto:

<Content>

<VsPackage>CustomDirectiveProcessor.dll</VsPackage>

</Content>

Distribuzione di un processore di direttiva in un package VS

Se il processore di direttiva fa parte di un package VS che sarà installato nella GAC, è possibile fare in modo che sia il sistema a generare il file .pkgdef.

Posizionare l'attributo seguente sulla classe del package:

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

Nota

Questo attributo viene posizionato sulla classe del package, non sulla classe del processore di direttiva.

Il file .pkgdef sarà generato quando si compila il progetto. Quando si installa il package VS, nel file .pkgdef verrà registrato il processore di direttiva.

Verificare che il file .pkgdef venga visualizzato nella cartella di compilazione, che in genere è bin\Debug o bin\Release. Se non è visualizzato, aprire il file .csproj in un editor di testo e rimuovere il nodo seguente: <GeneratePkgDefFile>false</GeneratePkgDefFile>.

Per ulteriori informazioni, vedere VSPackages.

Impostazione di una chiave di Registro di sistema

Questo metodo per installare un processore di direttiva personalizzato è il meno preferito. Non fornisce un modo comodo per abilitare e disabilitare il processore di direttiva e non fornisce un metodo per distribuire il processore di direttiva ad altri utenti.

Attenzione
Una modifica errata del Registro di sistema può provocare gravi danni al sistema. Prima di apportare modifiche al Registro di sistema, eseguire il backup dei dati importanti sul computer.

Per registrare un processore di direttiva impostando una chiave del Registro di sistema

Eseguire il comando regedit dal menu Start di Windows.
In regedit passare a

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

Se si desidera installare il processore di direttiva nella versione sperimentale di Visual Studio, inserire "Exp" dopo "10.0".
Aggiungere una chiave del Registro di sistema che abbia lo stesso nome della classe del processore di direttiva.
- Nella struttura ad albero del Registro di sistema, fare clic con il pulsante destro del mouse nel nodo DirectiveProcessors, selezionare Nuovo, quindi fare clic su Chiave.
Nel nuovo nodo, aggiungere valori stringa per Class e CodeBase o Assembly, sulla base delle tabelle seguenti.
1. Fare clic con il pulsante destro del mouse nel nodo creato, selezionare Nuovo, quindi fare clic su Valore stringa.
2. Modificare il nome del valore.
3. Fare doppio clic sul nome e modificare i dati.

Se il processore di direttiva personalizzato non è presente nella GAC, le sottochiavi del Registro di sistema appariranno come indicato nella tabella seguente:

Nome	Tipo	Dati
(Predefinito)	REG_SZ	(valore non impostato)
Classe	REG_SZ	<Nome spazio dei nomi>.<Nome classe>
CodeBase	REG_SZ	<Percorso>\<Nome assembly>

Se l'assembly è presente nella GAC, le sottochiavi del Registro di sistema appariranno come indicato nella tabella seguente:

Nome	Tipo	Dati
(Predefinito)	REG_SZ	(valore non impostato)
Classe	REG_SZ	<Nome classe completo>
Assembly	REG_SZ	<Nome assembly nella GAC>

Vedere anche

Concetti

Creazione di processori di direttiva di modelli di testo personalizzati

Condividi tramite