Invocar la transformación de texto en una extensión de VSInvoking Text Transformation in a VS Extension

Si está escribiendo una extensión de Visual Studio como un comando de menú o lenguaje específico de dominio, puede utilizar el servicio de plantillas de texto para transformar plantillas de texto.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. Obtenga el servicio STextTemplating y conviértalo a ITextTemplating.Get the STextTemplating service and cast it to ITextTemplating.

Obtener el servicio de plantillas de textoGetting 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));

Pasar parámetros a la plantillaPassing parameters to the template

Puede pasar parámetros en la plantilla.You can pass parameters into the template. Dentro de la plantilla, puede obtener los valores de parámetro mediante la directiva <#@parameter#>.Inside the template, you can get the parameter values by using the <#@parameter#> directive.

Para el tipo de parámetro, debe utilizar un tipo que sea serializable o que pueda calcular las referencias.For the type of a parameter, you must use a type that is serializable or that can be marshaled. Es decir, el tipo se debe declarar con SerializableAttribute o se debe derivar desde MarshalByRefObject.That is, the type must be declared with SerializableAttribute, or it must be derived from MarshalByRefObject. Esta restricción es necesaria porque la plantilla de texto se ejecuta en un AppDomain independiente.This restriction is necessary because the text template is executed in a separate AppDomain. Todos los tipos integrados como System.String y System.Int32 son serializables.All built-in types such as System.String and System.Int32 are serializable.

Para pasar valores de parámetro, el código de llamada puede colocar los valores en el diccionario Session o en el CallContext.To pass parameter values, the calling code can place values either in the Session dictionary, or in the CallContext.

En el siguiente ejemplo se utilizan ambos métodos para transformar una plantilla de pruebas corta: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

Informe de errores y la directiva de salidaError Reporting and the Output Directive

Los errores que surgen durante el proceso se mostrarán en la ventana de error de Visual StudioVisual Studio.Any errors that arise during processing will be displayed in the Visual StudioVisual Studio error window. Además, los errores se pueden notificar especificando una devolución de llamada que implementa ITextTemplatingCallback.In addition, you can be notified of errors by specifying a callback that implements ITextTemplatingCallback.

Si desea escribir la cadena de resultado a un archivo, puede que desee conocer la extensión de archivo y codificación que se han especificado en la directiva <#@output#> de la plantilla.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. Esta información también se pasará a la devolución de llamada.This information will also be passed to your callback. Para obtener más información, consulte directiva de salida 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; }
}

El código se puede probar con un archivo de plantilla similar al siguiente: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.

La advertencia del compilador aparecerá en la ventana de error de Visual StudioVisual Studio y también generará una llamada a ErrorCallback.The compiler warning will appear in the Visual StudioVisual Studio error window, and it will also generate a call to ErrorCallback.

Parámetros de referenciaReference parameters

Puede pasar valores de una plantilla de texto mediante una clase de parámetro que se deriva de MarshalByRefObject.You can pass values out of a text template by using a parameter class that is derived from MarshalByRefObject.

Para generar texto en una plantilla de texto preprocesada: llame a la TransformText() método de la clase generada.To generate text from a preprocessed text template: Call the TransformText() method of the generated class. Para obtener más información, consulte tiempo de ejecución de generación de texto con plantillas de texto T4.For more information, see Run-Time Text Generation with T4 Text Templates.

Para generar el texto fuera de un Visual StudioVisual Studio extensión: definir un host personalizado.To generate text outside a Visual StudioVisual Studio extension: Define a custom host. Para obtener más información, consulte de procesamiento de plantillas de texto mediante un Host personalizado.For more information, see Processing Text Templates by using a Custom Host.

Para generar código fuente que más adelante puede compilar y ejecutar: llame a la t4.PreprocessTemplate() método ITextTemplating.To generate source code that can later be compiled and executed: Call the t4.PreprocessTemplate() method of ITextTemplating.