Especificar eventos de build (C#)

Use eventos de build para especificar comandos que são executados antes do início do build ou após sua conclusão.

Especificar um evento de build

1. No Gerenciador de Soluções, selecione o projeto para o qual deseja especificar o evento de build.

2. No menu Projeto, clique em Propriedades de {Nome do projeto} (ou no Gerenciador de Soluções, pressione Alt+Enter).

3. Selecione Eventos de Build>.

   

4. Na seção Evento de pré-build, especifique a sintaxe do evento de build.

   Observação

   Eventos de pré-build não serão executados se o projeto estiver atualizado e nenhum build será disparado.

5. Na seção Evento de pós-build, especifique a sintaxe do evento de build.

   Observação

   Adicione uma instrução call antes de todos os comandos pós-build que executam arquivos .bat. Por exemplo, call MyFile.bat ou call MyFile.bat call MyFile2.bat. Os caminhos podem ser absolutos ou relativos à pasta do projeto.

6. Na caixa Executar o evento de pós-build, especifique em que condições o evento pós-build deve ser executado.

Criar os comandos do evento de build

Os comandos do evento de build podem incluir qualquer comando que seja válido em um prompt de comando ou em um arquivo .bat. Os comandos disponíveis estão documentados na referência de comandos do Windows. O nome de um arquivo em lote deve ser precedido por call para garantir que todos os comandos posteriores sejam executados. O próprio arquivo em lote é executado na pasta de saída, por exemplo, bin/Debug. Se você precisar do mesmo arquivo em lote para todas as configurações, poderá colocá-lo na mesma pasta que o arquivo de projeto e usar um caminho relativo para ele, por exemplo, call ../../prebuild.bat.

Você pode executar scripts do PowerShell inserindo um comando como PowerShell MyPowerShellScript.ps1. O caminho para o script do PowerShell pode ser absoluto ou pode ser relativo ao diretório do projeto. Você precisaria garantir que a política de execução de scripts do PowerShell no sistema operacional esteja definida adequadamente para executar o script. Consulte Sobre políticas de execução.

Para usar outro shell, como o bash, geralmente você usaria a mesma sintaxe de comando que usaria para iniciar um script de shell no prompt de comando do Windows. O uso de shells de terceiros está além do escopo desta documentação, mas sites como o Stack Overflow podem ser úteis.

No arquivo de projeto

Quando você executa as etapas anteriores, o Visual Studio modifica o arquivo de projeto adicionando o destino PreBuild ou PostBuild e o código do MSBuild necessário para executar as etapas fornecidas. Você pode abrir o arquivo de projeto e ver as etapas. É possível modificar as etapas no arquivo de projeto. Você verá as alterações na seção Build > Eventos das propriedades do projeto depois de salvá-las.

<Target Name="PreBuild" BeforeTargets="PreBuildEvent">
  <Exec Command="call prebuild.bat" />
</Target>

<Target Name="PostBuild" AfterTargets="PostBuildEvent">
  <Exec Command="call postbuild.bat" />
</Target>

O elemento Exec refere-se à tarefa Exec do MSBuild. Consulte Tarefa Exec para obter informações sobre quais outros parâmetros você pode usar para personalizar a execução. Por exemplo, você pode usar WorkingDirectory para definir a pasta da qual o executável é executado. O padrão é o diretório que contém o arquivo de projeto.

<Exec Command="call prebuild.bat" WorkingDirectory="$(OutDir)">

Você pode usar propriedades do MSBuild (macros), como OutDir no exemplo anterior, conforme discutido mais adiante neste artigo em Macros.

Erros e outras saídas

A saída dos eventos de build é gravada na seção Build da Janela de Saída. Para abri-la, escolha Exibir>Outras Janelas, Janela de Saída ou pressione Ctrl+Alt+O. Na lista suspensa ao lado de Mostrar saída de, escolha Build.

Se o evento de pré-build ou pós-build não for concluído com êxito, você poderá encerrar o build fazendo com que sua ação de evento saia com um código diferente de zero (0). O código de saída zero indica uma ação bem-sucedida; qualquer outro código de saída é considerado um erro.

Se o evento de pré-build falhar, você poderá ver um erro como este na janela Lista de Erros:

MSB3073    The command "call c:\source\repos\prebuild.bat" exited with code 1.

Se não houver informações suficientes na janela Lista de Erros, você poderá tentar usar a Janela de Saída para exibir a saída completa do build, incluindo qualquer saída de arquivos em lotes.

Dica

A janela Lista de Erros é limitada a apenas uma linha de saída, a primeira linha inserida para o evento. Se a saída da janela Lista de Erros for importante para você, evite colocar mais de uma linha no evento. Crie um arquivo em lote no prompt de comando do Windows ou no sistema operacional e use call mybatchfile.bat para o evento. Inclua os comandos no próprio arquivo em lote.

Para obter diretrizes sobre os comandos que você pode usar em arquivos em lote, consulte Comandos do Windows.

Macros

As "macros" normalmente disponíveis (na verdade propriedades do MSBuild) são listadas em propriedades comuns do MSBuild. Para projetos do SDK do .NET (.NET Core ou .NET 5 e posterior), propriedades adicionais são listadas em Propriedades do MSBuild para Microsoft.NET.Sdk.

Em seus scripts para eventos de build, talvez você queira referenciar os valores de algumas variáveis no nível do projeto, como o nome do projeto ou o local da pasta de saída. Em versões anteriores do Visual Studio, elas eram chamadas de macros. O equivalente a macros em versões recentes do Visual Studio são propriedades do MSBuild. O MSBuild é o mecanismo de build que o Visual Studio usa para processar o arquivo de projeto quando ele executa um build. Um evento de build no IDE resulta em um destino do MSBuild no arquivo de projeto. Você pode usar qualquer propriedade do MSBuild disponível no destino no arquivo de projeto (por exemplo, $(OutDir) ou $(Configuration)) . As propriedades do MSBuild que estão disponíveis para você nesses eventos dependem dos arquivos importados implicitamente ou explicitamente em um arquivo de projeto, como arquivos .props e propriedades .targets definidos em seu arquivo de projeto, como em elementos PropertyGroup. Tenha cuidado para usar a ortografia exata de cada propriedade. Nenhum erro será relatado se você digitar incorretamente uma propriedade; em vez disso, uma propriedade indefinida é avaliada como uma cadeia de caracteres vazia.

Por exemplo, suponha que você especifique um evento de pré-build da seguinte maneira:

Esse evento de pré-compilação resulta na seguinte entrada, chamada de Target no arquivo de projeto:

  <Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="echo Configuration: $(Configuration)&#xD;&#xA;echo DevEnvDir: $(DevEnvDir)&#xD;&#xA;echo OutDir: $(OutDir)&#xD;&#xA;echo ProjectDir: $(ProjectDir)&#xD;&#xA;echo VisualStudioVersion: $(VisualStudioVersion)&#xD;&#xA;echo AssemblySearchPaths: $(AssemblySearchPaths)&#xD;&#xA;echo AssemblyName: $(AssemblyName)&#xD;&#xA;echo BaseIntermediateOutputPath: $(BaseIntermediateOutputPath)&#xD;&#xA;echo CscToolPath: $(CscToolPath)" />
  </Target>

O evento de build aparece como um destino que inclui a tarefa Exec com a entrada especificada como Command. As linhas novas são codificadas no XML.

Quando você cria o projeto neste exemplo, o evento de pré-build imprime os valores de algumas propriedades. Neste exemplo, $(CscToolPath) não produz nenhuma saída, pois ela não está definida. É uma propriedade opcional que você pode definir em seu arquivo de projeto para dar o caminho para uma instância personalizada do compilador C# (por exemplo, se você estiver testando uma versão diferente de csc.exe ou um compilador experimental).

A saída dos eventos de build é gravada na saída de build, que pode ser encontrada na janela Saída. Na lista suspensa Mostrar saída, escolha Compilar.

Build started...
1>------ Build started: Project: ConsoleApp4, Configuration: Debug Any CPU ------
1>You are using a preview version of .NET. See: https://aka.ms/dotnet-core-preview
1>Configuration: Debug
1>DevEnvDir: C:\Program Files\Microsoft Visual Studio\2022\Preview\Common7\IDE\
1>OutDir: bin\Debug\net6.0\
1>ProjectDir: C:\source\repos\ConsoleApp4\ConsoleApp4\
1>VisualStudioVersion: 17.0
1>ALToolsPath:
1>AssemblySearchPaths: {CandidateAssemblyFiles};{HintPathFromItem};{TargetFrameworkDirectory};{RawFileName}
1>AssemblyName: ConsoleApp4
1>BaseIntermediateOutputPath: obj\
1>CscToolsPath:
1>Skipping analyzers to speed up the build. You can execute 'Build' or 'Rebuild' command to run analyzers.
1>ConsoleApp4 -> C:\source\repos\ConsoleApp4\ConsoleApp4\bin\Debug\net6.0\ConsoleApp4.dll

Observação

Alguns cenários exigem ações de build mais complexas do que os eventos de build são capazes. Por exemplo, para muitos cenários comuns de geração de código, você precisa lidar com operações limpas e de recompilação e talvez queira habilitar o build incremental para etapas de geração de código, de modo que a etapa seja executada somente se a saída estiver desatualizada em relação às entradas. O MSBuild foi projetado para lidar de modo inteligente com todos esses cenários. Considere criar um destino personalizado que especifique a execução de AfterTargets ou BeforeTargets durante um ponto específico no processo de build e, para obter mais controle em cenários avançados, considere criar uma tarefa personalizada, ou avalie as maneiras diferentes de Personalizar um build.

Exemplo

1. Crie um arquivo em lote chamado postbuild.bat na pasta do projeto, com o seguinte conteúdo:

   echo Copying output file %1 to %1.copy
   copy %1 %1.copy
   

   Lembre-se de que, em um arquivo em lote, %1 refere-se ao primeiro argumento passado.

2. Chame o arquivo em lote na seção Evento de pós-build das propriedades do projeto e passe um argumento usando a propriedade de MSBuild $(TargetPath).

   call postbuild.bat $(TargetPath)
   

3. Compile o projeto e verifique a pasta de saída. Você deverá ver o arquivo copiado ao lado do assembly compilado. Na Janela de Saída, na seção Build, você deverá ver a saída do arquivo em lote:

   1>Output file is C:\source\repos\ConsoleApp-BuildEvents\ConsoleApp-BuildEvents\bin\Debug\net6.0\ConsoleApp-BuildEvents.dll
   1>        1 file(s) copied.
   ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
   ========== Build started at 12:00 PM and took 00.723 seconds ==========
   

Conteúdo relacionado

• Página Eventos de Build, Designer de Projeto (C#)
• Caixa de diálogo da linha de comando do evento de pré-build/evento de pós-build
• Como especificar eventos de build (Visual Basic)
• Compilar e criar