Tareas insertadas de MSBuildMSBuild inline tasks

Las tareas de MSBuild se crean normalmente compilando una clase que implementa la interfaz ITask.MSBuild tasks are typically created by compiling a class that implements the ITask interface. Para obtener más información, consulte Tareas.For more information, see Tasks.

A partir de .NET Framework versión 4, se pueden crear tareas insertadas en el archivo del proyecto.Starting in .NET Framework version 4, you can create tasks inline in the project file. No es necesario crear un ensamblado independiente para hospedar la tarea.You do not have to create a separate assembly to host the task. Esto facilita el seguimiento del código fuente y la implementación de la tarea.This makes it easier to keep track of source code and easier to deploy the task. El código fuente se integra en el script.The source code is integrated into the script.

En MSBuild 15.8, se ha agregado RoslynCodeTaskFactory, que puede crear tareas insertadas multiplataforma de .NET Standard.In MSBuild 15.8, the RoslynCodeTaskFactory was added which can create .NET Standard cross-platform inline tasks. Si necesita usar tareas insertadas en .NET Core, debe emplear RoslynCodeTaskFactory.If you need to use inline tasks on .NET Core, you must use the RoslynCodeTaskFactory.

Estructura de una tarea insertadaThe structure of an inline task

Una tarea insertada está contenida en un elemento UsingTask.An inline task is contained by a UsingTask element. La tarea insertada y el elemento UsingTask que la contiene se suelen incluir en un archivo .targets y se importan en otros archivos de proyecto según se requiera.The inline task and the UsingTask element that contains it are typically included in a .targets file and imported into other project files as required. A continuación se muestra una tarea insertada básica.Here is a basic inline task. Observe que no se realiza ninguna acción.Notice that it does nothing.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  
  <!-- This simple inline task does nothing. -->  
  <UsingTask  
    TaskName="DoNothing"  
    TaskFactory="CodeTaskFactory"  
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" >  
    <ParameterGroup />  
    <Task>  
      <Reference Include="" />  
      <Using Namespace="" />  
      <Code Type="Fragment" Language="cs">  
      </Code>  
    </Task>  
  </UsingTask>  
</Project>  

El elemento UsingTask del ejemplo tiene tres atributos que describen la tarea y el generador de tareas insertadas que lo compila.The UsingTask element in the example has three attributes that describe the task and the inline task factory that compiles it.

  • El atributo TaskName asigna un nombre a la tarea, en este caso, DoNothing.The TaskName attribute names the task, in this case, DoNothing.

  • El atributo TaskFactory asigna un nombre a la clase que implementa el generador de tareas insertadas.The TaskFactory attribute names the class that implements the inline task factory.

  • El atributo AssemblyFile proporciona la ubicación del generador de tareas insertadas.The AssemblyFile attribute gives the location of the inline task factory. Alternativamente, puede utilizar el atributo AssemblyName para especificar el nombre completo de la clase de generador de tareas insertadas, que está ubicada normalmente en la caché global de ensamblados (GAC).Alternatively, you can use the AssemblyName attribute to specify the fully qualified name of the inline task factory class, which is typically located in the global assembly cache (GAC).

Los elementos restantes de la tarea DoNothing están vacíos y se proporcionan para mostrar el orden y la estructura de una tarea insertada.The remaining elements of the DoNothing task are empty and are provided to illustrate the order and structure of an inline task. Un ejemplo más completo se presenta posteriormente en este tema.A more robust example is presented later in this topic.

  • El elemento ParameterGroup es opcional.The ParameterGroup element is optional. Cuando se especifica, declara los parámetros para la tarea.When specified, it declares the parameters for the task. Para obtener más información sobre los parámetros de entrada y salida, vea Parámetros de entrada y salida más adelante en este tema.For more information about input and output parameters, see Input and output parameters later in this topic.

  • El elemento Task describe y contiene el código fuente de la tarea.The Task element describes and contains the task source code.

  • El elemento Reference especifica las referencias a los ensamblados de .NET que se utilizan en el código.The Reference element specifies references to the .NET assemblies that you are using in your code. Esto es equivalente a agregar una referencia a un proyecto en Visual Studio.This is equivalent to adding a reference to a project in Visual Studio. El atributo Include especifica la ruta de acceso del ensamblado al que se hace referencia.The Include attribute specifies the path of the referenced assembly.

  • El elemento Using enumera los espacios de nombres a los que se desea obtener acceso.The Using element lists the namespaces that you want to access. Esto es similar a la instrucción Using de Visual C#.This resembles the Using statement in Visual C#. El atributo Namespace especifica el espacio de nombres que se va a incluir.The Namespace attribute specifies the namespace to include.

Los elementos Reference y Using son independientes del lenguaje.Reference and Using elements are language-agnostic. Las tareas insertadas se pueden escribir en cualquiera de los lenguajes CodeDom para .NET admitidos, por ejemplo, Visual Basic o Visual C#.Inline tasks can be written in any one of the supported .NET CodeDom languages, for example, Visual Basic or Visual C#.

Nota

Los elementos contenidos en el elemento Task son específicos del generador de tareas, en este caso, el generador de tareas de código.Elements contained by the Task element are specific to the task factory, in this case, the code task factory.

Elemento de códigoCode element

El último elemento secundario que aparece dentro del elemento Task es el elemento Code.The last child element to appear within the Task element is the Code element. El elemento Code contiene o localiza el código que se desea compilar en una tarea.The Code element contains or locates the code that you want to be compiled into a task. Lo que se incluye en el elemento Code depende de cómo se desea escribir la tarea.What you put in the Code element depends on how you want to write the task.

El atributo Language especifica el lenguaje en el que se escribe el código.The Language attribute specifies the language in which your code is written. Los valores aceptables son cs para C#, vb para Visual Basic.Acceptable values are cs for C#, vb for Visual Basic.

El atributo Type especifica el tipo de código que se encuentra en el elemento Code.The Type attribute specifies the type of code that is found in the Code element.

  • Si el valor de Type es Class, el elemento Code contiene el código para una clase que deriva de la interfaz ITask.If the value of Type is Class, then the Code element contains code for a class that derives from the ITask interface.

  • Si el valor de Type es Method, el código define un reemplazo del método Execute de la interfaz ITask.If the value of Type is Method, then the code defines an override of the Execute method of the ITask interface.

  • Si el valor de Type es Fragment, el código define el contenido del método Execute, pero no la firma o la instrucción return.If the value of Type is Fragment, then the code defines the contents of the Execute method, but not the signature or the return statement.

El propio código aparece normalmente entre un marcador <![CDATA[ y un marcador ]]>.The code itself typically appears between a <![CDATA[ marker and a ]]> marker. Dado que el código está en una sección CDATA, no tiene que preocuparse de anteponer caracteres de escape a los caracteres reservados, como "<" o ">".Because the code is in a CDATA section, you do not have to worry about escaping reserved characters, for example, "<" or ">".

Alternativamente, puede utilizar el atributo Source del elemento Code para especificar la ubicación de un archivo que contiene el código para la tarea.Alternatively, you can use the Source attribute of the Code element to specify the location of a file that contains the code for your task. El código del archivo de código fuente debe ser del tipo especificado por el atributo Type.The code in the source file must be of the type that is specified by the Type attribute. Si el atributo Source está presente, el valor predeterminado de Type es Class.If the Source attribute is present, the default value of Type is Class. Si Source no está presente, el valor predeterminado es Fragment.If Source is not present, the default value is Fragment.

Nota

Al definir la clase de tarea en el archivo de origen, el nombre de clase debe corresponder al atributo TaskName del elemento UsingTask correspondiente.When defining the task class in the source file, the class name must agree with the TaskName attribute of the corresponding UsingTask element.

HelloWorldHelloWorld

A continuación se muestra una tarea insertada más completa.Here is a more robust inline task. La tarea HelloWorld muestra "Hello, world!"The HelloWorld task displays "Hello, world!" en el dispositivo de registro de errores predeterminado, que suele ser la consola del sistema o la ventana de salida de Visual Studio.on the default error logging device, which is typically the system console or the Visual Studio Output window. El elemento Reference del ejemplo se incluye solamente a efectos de ilustración.The Reference element in the example is included just for illustration.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  
  <!-- This simple inline task displays "Hello, world!" -->  
  <UsingTask  
    TaskName="HelloWorld"  
    TaskFactory="CodeTaskFactory"  
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" >  
    <ParameterGroup />  
    <Task>  
      <Reference Include="System.Xml"/>
      <Using Namespace="System"/>  
      <Using Namespace="System.IO"/>  
      <Code Type="Fragment" Language="cs">  
<![CDATA[  
// Display "Hello, world!"  
Log.LogError("Hello, world!");  
]]>  
      </Code>  
    </Task>  
  </UsingTask>  
</Project>  

Puede guardar la tarea HelloWorld en un archivo denominado HelloWorld.targets y luego invocarlo desde un proyecto del modo siguiente.You could save the HelloWorld task in a file that is named HelloWorld.targets, and then invoke it from a project as follows.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  
  <Import Project="HelloWorld.targets" />  
  <Target Name="Hello">  
    <HelloWorld />  
  </Target>  
</Project>  

Parámetros de entrada y salidaInput and output parameters

Los parámetros de las tareas insertadas son elementos secundarios de un elemento ParameterGroup.Inline task parameters are child elements of a ParameterGroup element. Cada parámetro toma el nombre del elemento que lo define.Every parameter takes the name of the element that defines it. En el código siguiente se define el parámetro Text.The following code defines the parameter Text.

<ParameterGroup>  
    <Text />  
</ParameterGroup>  

Los parámetros pueden tener uno o más de estos atributos:Parameters may have one or more of these attributes:

  • Required es un atributo opcional que es false de forma predeterminada.Required is an optional attribute that is false by default. Si es true, el parámetro es necesario y se le debe proporcionar un valor antes de llamar a la tarea.If true, then the parameter is required and must be given a value before calling the task.

  • ParameterType es un atributo opcional que es System.String de forma predeterminada.ParameterType is an optional attribute that is System.String by default. Se puede establecer en cualquier tipo completo que sea un elemento o un valor que se pueda convertir a y de una cadena utilizando System.Convert.ChangeType.It may be set to any fully qualified type that is either an item or a value that can be converted to and from a string by using System.Convert.ChangeType. (En otras palabras, cualquier tipo que se pueda pasar a y desde una tarea externa).(In other words, any type that can be passed to and from an external task.)

  • Output es un atributo opcional que es false de forma predeterminada.Output is an optional attribute that is false by default. Si es true, se debe proporcionar al parámetro un valor antes de volver del método Execute.If true, then the parameter must be given a value before returning from the Execute method.

Por ejemplo,For example,

<ParameterGroup>  
    <Expression Required="true" />  
      <Files ParameterType="Microsoft.Build.Framework.ITaskItem[]" Required="true" />  
    <Tally ParameterType="System.Int32" Output="true" />  
</ParameterGroup>  

define estos tres parámetros:defines these three parameters:

  • Expression es un parámetro de entrada necesario de tipo System.String.Expression is a required input parameter of type System.String.

  • Files es un parámetro de entrada de lista de elementos necesario.Files is a required item list input parameter.

  • Tally es un parámetro de salida de tipo System.Int32.Tally is an output parameter of type System.Int32.

Si el elemento Code tiene el atributo Type de Fragment o Method, las propiedades se crean automáticamente para cada parámetro.If the Code element has the Type attribute of Fragment or Method, then properties are automatically created for every parameter. De lo contrario, las propiedades se deben declarar explícitamente en el código fuente de la tarea y deben coincidir exactamente con sus definiciones de parámetro.Otherwise, properties must be explicitly declared in the task source code, and must exactly match their parameter definitions.

EjemploExample

La tarea insertada siguiente reemplaza cada aparición de un token en el archivo determinado por el valor determinado.The following inline task replaces every occurrence of a token in the given file with the given value.

<Project xmlns='http://schemas.microsoft.com/developer/msbuild/2003' ToolsVersion="15.0">  

  <UsingTask TaskName="TokenReplace" TaskFactory="CodeTaskFactory" AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll">  
    <ParameterGroup>  
      <Path ParameterType="System.String" Required="true" />  
      <Token ParameterType="System.String" Required="true" />  
      <Replacement ParameterType="System.String" Required="true" />  
    </ParameterGroup>  
    <Task>  
      <Code Type="Fragment" Language="cs"><![CDATA[  
string content = File.ReadAllText(Path);  
content = content.Replace(Token, Replacement);  
File.WriteAllText(Path, content);  

]]></Code>  
    </Task>  
  </UsingTask>  

  <Target Name='Demo' >  
    <TokenReplace Path="C:\Project\Target.config" Token="$MyToken$" Replacement="MyValue"/>  
  </Target>  
</Project>  

Vea tambiénSee also

Tareas Tasks
Tutorial: Creación de una tarea insertadaWalkthrough: Create an inline task