Especificar eventos de build (C#)

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

Especificar um evento de build

1. Em do Gerenciador de Soluções, selecione o projeto para o qual você deseja especificar o evento de build.

2. No menu Project, clique em {ProjectName} Properties (ou no do 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

   Os eventos de pré-compilação não serão executados se o projeto estiver atualizado e nenhuma compilação for disparada.

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 comandos de evento de compilação

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 subsequentes 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 verificar se a política de execução para scripts do PowerShell em seu sistema operacional está definida adequadamente para executar o script. Confira Sobre políticas de execução.

Se você quiser usar outro shell, como o bash, geralmente usaria a mesma sintaxe de comando que usaria para iniciar um script de shell do 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 PreBuild ou PostBuild destino e o código MSBuild necessário para executar as etapas fornecidas. Você pode abrir o arquivo de projeto e ver as etapas. Modificar as etapas no arquivo de projeto é bom. 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 MSBuild. Consulte a tarefa de execução para obter informações sobre os outros parâmetros que 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 as propriedades do MSBuild (macros), como OutDir no exemplo anterior, conforme discutido posteriormente neste artigo no Macros.

Erros e outros resultados

A saída dos eventos de build é gravada na seção Build da Janela de Saída. Para abri-lo, 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é-construção ou pós-construção não for concluído com êxito, você poderá encerrar a construção fazendo com que a ação do evento seja finalizada com um código diferente de zero (0). Um 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.

Gorjeta

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 lotes, 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 de SDK do .NET (.NET Core ou .NET 5 e versões posteriores), propriedades adicionais são listadas em propriedades do MSBuild para Microsoft.NET.Sdk.

Em seus scripts para eventos de build, convém 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 do arquivo de projeto (por exemplo, $(OutDir) ou $(Configuration)). As propriedades do MSBuild que estão disponíveis para você nesses eventos dependem dos arquivos implicitamente ou explicitamente importados em um arquivo de projeto, como arquivos .props e .targets e propriedades definidas 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é-construção da seguinte maneira:

Esse evento de pré-build resulta na seguinte entrada, chamada de Target em seu 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é-construção imprime os valores de algumas propriedades. Neste exemplo, $(CscToolPath) não produz nenhuma saída, pois não está definida. É uma propriedade opcional que você pode definir em seu arquivo de projeto para dar o caminho a uma instância personalizada do compilador C# (por exemplo, se você estiver testando uma versão diferente do csc.exeou de 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 inteligentemente 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. Crie seu 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 construir