Appel d’une transformation de texte dans une extension VSInvoking Text Transformation in a VS Extension

Si vous écrivez une extension de Visual Studio, telle qu’une commande de menu ou langage spécifique à un domaine, vous pouvez utiliser le service de création de modèles de texte pour transformer des modèles de texte.If you are writing a Visual Studio extension such as a menu command or domain-specific language, you can use the text templating service to transform text templates. Obtenez le service STextTemplating et effectuez le cast de celui-ci en ITextTemplating.Get the STextTemplating service and cast it to ITextTemplating.

Obtention du service de création de modèles de texteGetting the text templating service

using Microsoft.VisualStudio.TextTemplating;  
using Microsoft.VisualStudio.TextTemplating.VSHost;  
...  
// Get a service provider - how you do this depends on the context:  
IServiceProvider serviceProvider = ...; // An instance of EnvDTE, for example   

// Get the text template service:  
ITextTemplating t4 = serviceProvider.GetService(typeof(STextTemplating)) as ITextTemplating;  

// Process a text template:  
string result = t4.ProcessTemplate(filePath, System.IO.File.ReadAllText(filePath));  

Transmission des paramètres au modèlePassing parameters to the template

Vous pouvez passer des paramètres dans le modèle.You can pass parameters into the template. À l'intérieur du modèle, vous pouvez obtenir les valeurs de paramètre à l'aide de la directive <#@parameter#>.Inside the template, you can get the parameter values by using the <#@parameter#> directive.

Pour le type d'un paramètre, vous devez utiliser un type qui est sérialisable ou qui peut être marshalé.For the type of a parameter, you must use a type that is serializable or that can be marshaled. Autrement dit, le type doit être déclaré avec SerializableAttribute, ou il doit être dérivé de MarshalByRefObject.That is, the type must be declared with SerializableAttribute, or it must be derived from MarshalByRefObject. Cette restriction est nécessaire car le modèle de texte est exécuté dans un AppDomain séparé.This restriction is necessary because the text template is executed in a separate AppDomain. Tous les types intégrés tels que System.String et System.Int32 sont sérialisables.All built-in types such as System.String and System.Int32 are serializable.

Pour passer des valeurs de paramètre, le code appelant peut placer des valeurs dans le dictionnaire Session ou dans le CallContext.To pass parameter values, the calling code can place values either in the Session dictionary, or in the CallContext.

L'exemple suivant utilise les deux méthodes pour transformer un modèle de test court :The following example uses both methods to transform a short test template:

using Microsoft.VisualStudio.TextTemplating;  
using Microsoft.VisualStudio.TextTemplating.VSHost;  
...  
// Get a service provider - how you do this depends on the context:  
IServiceProvider serviceProvider = dte;   

// Get the text template service:  
ITextTemplating t4 = serviceProvider.GetService(typeof(STextTemplating)) as ITextTemplating;  
ITextTemplatingSessionHost sessionHost = t4 as ITextTemplatingSessionHost;  

// Create a Session in which to pass parameters:  
sessionHost.Session = sessionHost.CreateSession();  
sessionHost.Session["parameter1"] = "Hello";  
sessionHost.Session["parameter2"] = DateTime.Now;  

// Pass another value in CallContext:  
System.Runtime.Remoting.Messaging.CallContext.LogicalSetData("parameter3", 42);  

// Process a text template:  
string result = t4.ProcessTemplate("",  
   // This is the test template:  
   "<#@parameter type=\"System.String\" name=\"parameter1\"#>"  
 + "<#@parameter type=\"System.DateTime\" name=\"parameter2\"#>"  
 + "<#@parameter type=\"System.Int32\" name=\"parameter3\"#>"  
 + "Test: <#=parameter1#>    <#=parameter2#>    <#=parameter3#>");  

// This test code yields a result similar to the following line:  
//     Test: Hello    07/06/2010 12:37:45    42  

Rapport d'erreurs et directive de sortieError Reporting and the Output Directive

Toutes les erreurs qui surviennent pendant le traitement seront affichées dans la fenêtre d'erreur Visual StudioVisual Studio.Any errors that arise during processing will be displayed in the Visual StudioVisual Studio error window. De plus, vous pouvez être informé des erreurs en spécifiant un rappel qui implémente ITextTemplatingCallback.In addition, you can be notified of errors by specifying a callback that implements ITextTemplatingCallback.

Si vous souhaitez écrire la chaîne de résultat dans un fichier, vous souhaitez peut-être connaître l'extension de fichier et l'encodage spécifiés dans la directive <#@output#> dans le modèle.If you want to write the result string to a file, you might want to know what file extension and encoding have been specified in the <#@output#> directive in the template. Ces informations seront également passées à votre rappel.This information will also be passed to your callback. Pour plus d’informations, consultez Directive de sortie T4.For more information, see T4 Output Directive.

void ProcessMyTemplate(string MyTemplateFile)  
{  
  string templateContent = File.ReadAllText(MyTemplateFile);  
  T4Callback cb = new T4Callback();  
  // Process a text template:  
  string result = t4.ProcessTemplate(MyTemplateFile, templateContent, cb);  
  // If there was an output directive in the MyTemplateFile,  
  // then cb.SetFileExtension() will have been called.  
  // Determine the output file name:  
  string resultFileName =   
    Path.Combine(Path.GetDirectoryName(MyTemplateFile),   
        Path.GetFileNameWithoutExtension(MyTemplateFile))   
      + cb.fileExtension;  
  // Write the processed output to file:  
  File.WriteAllText(resultFileName, result, cb.outputEncoding);  
  // Append any error messages:  
  if (cb.errorMessages.Count > 0)  
  {  
    File.AppendAllLines(resultFileName, cb.errorMessages);  
  }  
}  

class T4Callback : ITextTemplatingCallback  
{  
  public List<string> errorMessages = new List<string>();  
  public string fileExtension = ".txt";  
  public Encoding outputEncoding = Encoding.UTF8;  

  public void ErrorCallback(bool warning, string message, int line, int column)  
  { errorMessages.Add(message); }  

  public void SetFileExtension(string extension)  
  { fileExtension = extension; }  

  public void SetOutputEncoding(Encoding encoding, bool fromOutputDirective)  
  { outputEncoding = encoding; }  
}  

Le code peut être testé avec un fichier modèle semblable au suivant :The code can be tested with a template file similar to the following:

<#@output extension=".htm" encoding="ASCII"#>  
<# int unused;  // Compiler warning "unused variable"  
#>  
Sample text.  

L'avertissement du compilateur s'affichera dans la fenêtre d'erreur Visual StudioVisual Studio, et un appel à ErrorCallback sera également généré.The compiler warning will appear in the Visual StudioVisual Studio error window, and it will also generate a call to ErrorCallback.

Paramètres de référenceReference parameters

Vous pouvez passer des valeurs en dehors d'un modèle de texte à l'aide d'une classe de paramètre dérivée de MarshalByRefObject.You can pass values out of a text template by using a parameter class that is derived from MarshalByRefObject.

Pour générer du texte à partir d'un modèle de texte prétraité :To generate text from a preprocessed text template:
Appelez la méthode TransformText() de la classe générée.Call the TransformText() method of the generated class. Pour plus d’informations, consultez génération de texte d’exécution avec les modèles de texte T4.For more information, see Run-Time Text Generation with T4 Text Templates.

Pour générer du texte en dehors d'une extension Visual StudioVisual Studio :To generate text outside a Visual StudioVisual Studio extension:
Définissez un hôte personnalisé.Define a custom host. Pour plus d’informations, consultez le traitement des modèles de texte à l’aide d’un hôte personnalisé.For more information, see Processing Text Templates by using a Custom Host.

Pour générer du code source qui peut ensuite être compilé et exécuté :To generate source code that can later be compiled and executed:
Appelez la méthode t4.PreprocessTemplate() de ITextTemplating.Call the t4.PreprocessTemplate() method of ITextTemplating.