Produção de tarefas

Tarefas fornecem o código que é executado durante o processo de build. Tarefas estão contidas nos destinos. uma biblioteca de tarefas típicas está incluída no MSBuild, e você também pode criar suas próprias tarefas. para obter mais informações sobre a biblioteca de tarefas que estão incluídas com MSBuild, consulte referência de tarefas.

Tarefas

Exemplos de tarefas incluem cópia, que copia um ou mais arquivos, MakeDir, que cria um diretório e CSC, que compila arquivos de código-fonte C#. Cada tarefa é implementada como uma classe do .NET que implementa a interface ITask, a qual é definida no assembly Microsoft.Build.Framework.dll.

Há duas abordagens que você pode usar ao implementar uma tarefa:

  • Implemente a interface ITask diretamente.

  • Derive sua classe da classe auxiliar Task , que é definida no assembly Microsoft.Build.Utilities.dll . Tarefa implementa ITask e fornece implementações padrão de alguns membros do ITask. Além disso, o registro em log é mais fácil.

Em ambos os casos, você deve adicionar à sua classe um método chamado Execute, que é o método que é chamado quando a tarefa é executada. Esse método não usa nenhum parâmetro e retorna um Boolean valor: true se a tarefa foi bem-sucedida ou false se falhou. O exemplo a seguir mostra uma tarefa que não executa nenhuma ação e é concluída com êxito (retorna true ).

using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;

namespace MyTasks
{
    public class SimpleTask : Task
    {
        public override bool Execute()
        {
            return true;
        }
    }
}

O arquivo de projeto a seguir executa essa tarefa:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="MyTarget">
        <SimpleTask />
    </Target>
</Project>

Quando executar tarefas, elas também poderá receber entradas do arquivo de projeto se você criar propriedades .NET na classe task. MSBuild define essas propriedades imediatamente antes de chamar o método da tarefa Execute . Para criar uma propriedade de cadeia de caracteres, use o código da tarefa como:

using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;

namespace MyTasks
{
    public class SimpleTask : Task
    {
        public override bool Execute()
        {
            return true;
        }

        public string MyProperty { get; set; }
    }
}

O seguinte arquivo de projeto executa essa tarefa e define MyProperty como o valor especificado:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Target Name="MyTarget">
      <SimpleTask MyProperty="Value for MyProperty" />
   </Target>
</Project>

Tarefas de registro

se um projeto vai executar uma tarefa, MSBuild deve saber como localizar e executar o assembly que contém a classe task. As tarefas são registradas usando o elemento UsingTask (MSBuild).

se sua tarefa tiver dependências específicas de tempo de execução, você deverá informar MSBuild que ela deve executar a tarefa em um ambiente específico, indicando o Architecture e/ou Runtime em seu UsingTask.

o arquivo de MSBuild Microsoft. Common. tasks é um arquivo de projeto que contém uma lista de UsingTask elementos que registram todas as tarefas que são fornecidas com MSBuild. Esse arquivo é incluído automaticamente durante a compilação de qualquer projeto. Se uma tarefa registrada em Microsoft. Common. Tasks também estiver registrada no arquivo de projeto atual, o arquivo de projeto atual terá precedência, para que você possa substituir uma tarefa padrão por sua própria tarefa que tenha o mesmo nome.

Dica

você pode ver uma lista das tarefas que são fornecidas com uma versão específica do MSBuild exibindo o conteúdo de sua Microsoft. Common. tasks.

Gerar eventos de uma tarefa

Se a tarefa deriva da classe auxiliar Task, você pode usar qualquer um dos seguintes métodos auxiliares na classe Task para acionar eventos que serão capturados e exibidos por quaisquer agentes registrados:

public override bool Execute()
{
    Log.LogError("messageResource1", "1", "2", "3");
    Log.LogWarning("messageResource2");
    Log.LogMessage(MessageImportance.High, "messageResource3");
    ...
}

Se a tarefa implementa ITask diretamente, você ainda pode acionar esses eventos, mas deve usar a interface IBuildEngine. O exemplo a seguir mostra uma tarefa que implementa ITask e gera um evento personalizado:

public class SimpleTask : ITask
{
    public IBuildEngine BuildEngine { get; set; }

    public override bool Execute()
    {
        TaskEventArgs taskEvent =
            new TaskEventArgs(BuildEventCategory.Custom,
            BuildEventImportance.High, "Important Message",
           "SimpleTask");
        BuildEngine.LogBuildEvent(taskEvent);
        return true;
    }
}

Parâmetros de tarefa que precisam de configuração

Você pode marcar determinadas propriedades de tarefa como "necessárias" para que qualquer arquivo de projeto que executa a tarefa deve definir valores para essas propriedades ou o build falhará. Aplicar o atributo [Required] à propriedade .NET em sua tarefa da seguinte maneira:

[Required]
public string RequiredProperty { get; set; }

O atributo [Required] é definido por RequiredAttribute no namespace Microsoft.Build.Framework.

como MSBuild invoca uma tarefa

ao invocar uma tarefa, MSBuild primeiro instancia a classe task e, em seguida, chama os setters de propriedade do objeto para os parâmetros de tarefa que são definidos no elemento task no arquivo de projeto. Se o elemento Task não especificar um parâmetro ou se a expressão especificada no elemento for avaliada como uma cadeia de caracteres vazia, o setter da propriedade não será chamado.

Por exemplo, no projeto

<Project>
 <Target Name="InvokeCustomTask">
  <CustomTask Input1=""
              Input2="$(PropertyThatIsNotDefined)"
              Input3="value3" />
 </Target>
</Project>

somente o setter para Input3 é chamado.

Uma tarefa não deve depender de nenhuma ordem relativa da invocação de setter de propriedade de parâmetro.

Tipos de parâmetro de tarefa

o MSBuild manipula nativamente as propriedades do tipo string , bool ITaskItem e ITaskItem[] . se uma tarefa aceitar um parâmetro de um tipo diferente, MSBuild invocará ChangeType a conversão de string (com todas as referências de item e propriedade expandidas) para o tipo de destino. se a conversão falhar para qualquer parâmetro de entrada, o MSBuild emitirá um erro e não chamará o Execute() método da tarefa.

Exemplo 1

Descrição

Essa classe C# a seguir demonstra uma tarefa derivada da Task classe auxiliar. Esta tarefa retorna true, indicando que foi bem-sucedida.

Código

using System;
using Microsoft.Build.Utilities;

namespace SimpleTask1
{
    public class SimpleTask1: Task
    {
        public override bool Execute()
        {
            // This is where the task would presumably do its work.
            return true;
        }
    }
}

Exemplo 2

Descrição

Essa classe C# a seguir demonstra uma tarefa que implementa a ITask interface. Esta tarefa retorna true, indicando que foi bem-sucedida.

Código

using System;
using Microsoft.Build.Framework;

namespace SimpleTask2
{
    public class SimpleTask2: ITask
    {
        //When implementing the ITask interface, it is necessary to
        //implement a BuildEngine property of type
        //Microsoft.Build.Framework.IBuildEngine. This is done for
        //you if you derive from the Task class.
        public IBuildEngine BuildEngine { get; set; }

        // When implementing the ITask interface, it is necessary to
        // implement a HostObject property of type object.
        // This is done for you if you derive from the Task class.
        public object HostObject { get; set; }

        public bool Execute()
        {
            // This is where the task would presumably do its work.
            return true;
        }
    }
}

Exemplo 3

Descrição

Essa classe C# demonstra uma tarefa derivada da Task classe auxiliar. Tem uma propriedade de cadeia de caracteres obrigatória e gera um evento que é exibido por todos os agentes registrados.

Código

using System;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;

namespace SimpleTask3
{
    public class SimpleTask3 : Task
    {
        private string myProperty;

        // The [Required] attribute indicates a required property.
        // If a project file invokes this task without passing a value
        // to this property, the build will fail immediately.
        [Required]
        public string MyProperty
        {
            get
            {
                return myProperty;
            }
            set
            {
                myProperty = value;
            }
        }

        public override bool Execute()
        {
            // Log a high-importance comment
            Log.LogMessage(MessageImportance.High,
                "The task was passed \"" + myProperty + "\".");
            return true;
        }
    }
}

Exemplo 4

Descrição

O exemplo a seguir mostra um arquivo de projeto invocando a tarefa de exemplo anterior, SimpleTask3.

Código

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <UsingTask TaskName="SimpleTask3.SimpleTask3"
        AssemblyFile="SimpleTask3\bin\debug\simpletask3.dll"/>

    <Target Name="MyTarget">
        <SimpleTask3 MyProperty="Hello!"/>
    </Target>
</Project>

Confira também