Указание событий сборки (C#)

Используйте события сборки, чтобы указать команды, выполняемые до начала сборки или после завершения сборки.

Указание события сборки

1. В обозревателе решенийвыберите проект, для которого нужно указать событие сборки.

2. В меню проекта щелкните свойства {ProjectName} (или из обозревателя решений, нажмите клавиш Alt+Enter).

3. Выберите Сборка событий >.

   

4. В разделе события предварительной сборки укажите синтаксис события сборки.

   Заметка

   События предварительной сборки не выполняются, если проект обновлён и сборка не запускается.

5. В разделе события после сборки укажите синтаксис события сборки.

   Заметка

   Добавьте инструкцию call перед всеми командами после сборки, выполняющими .bat файлы. Например, call MyFile.bat или call MyFile.bat call MyFile2.bat. Пути могут быть абсолютными или относительными к папке проекта.

6. В разделе При запуске события после сборки укажите, в каких условиях необходимо выполнить событие после сборки.

Создание команд событий сборки

Команды события сборки могут включать любую команду, допустимую в командной строке или в файле .bat. Доступные команды описаны в справочнике по командам Windows. Имя пакетного файла должно предшествовать call, чтобы обеспечить выполнение всех последующих команд. Пакетный файл запускается из выходной папки, например bin/Debug. Если вам нужен один пакетный файл для всех конфигураций, его можно поместить в ту же папку, что и файл проекта, и использовать относительный путь к нему, например, call ../../prebuild.bat.

Можно выполнить скрипты PowerShell, введя команду, например PowerShell MyPowerShellScript.ps1. Путь к скрипту PowerShell может быть абсолютным или может быть относительным к каталогу проекта. Необходимо убедиться, что политика выполнения сценариев PowerShell в операционной системе настроена соответствующим образом, чтобы запустить скрипт. См. о политиках выполнения.

Если вы хотите использовать другую оболочку, например bash, вы обычно используете тот же синтаксис команды, что и для запуска скрипта оболочки из командной строки Windows. Использование сторонних оболочков выходит за рамки этой документации, но такие сайты, как Stack Overflow, могут оказаться полезными.

В файле проекта

При выполнении предыдущих действий Visual Studio изменяет файл проекта, добавив PreBuild или PostBuild целевой объект и необходимый код MSBuild для выполнения указанных действий. Вы можете открыть файл проекта и просмотреть шаги. Допускается изменение шагов в файле проекта. После сохранения изменений вы увидите их в разделе "Сборка" > "События" свойств проекта.

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

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

Элемент Exec ссылается на задачу MSBuild Exec. См. задачу Exec и пункт для информации о других параметрах, которые можно использовать для настройки выполнения. Например, можно использовать WorkingDirectory для задания папки, из которой выполняется исполняемый файл. По умолчанию используется каталог, содержащий файл проекта.

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

В предыдущем примере можно использовать свойства MSBuild (макросы), такие как OutDir, что позже обсуждается в этой статье в разделе Макросы.

Ошибки и другие выходные данные

Выходные данные ваших событий сборки записываются в раздел Сборка окна вывода . Чтобы открыть его, выберите Просмотр>Другие окна, Окно вывода, или нажмите клавиши Ctrl+Alt+O. В раскрывающемся списке рядом с Показывать выходные данные извыберите Сборка.

Если событие предварительной сборки или после сборки не завершено успешно, можно завершить сборку, завершив действие события кодом, отличном от нуля (0). Нулевой код выхода указывает на успешное действие; любой другой код выхода считается ошибкой.

Если событие предварительной сборки завершается сбоем, в окне Список ошибок может появиться ошибка:

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

Если в окне списка ошибок недостаточно сведений, можно попробовать использовать окно вывода , чтобы просмотреть все выходные данные сборки, включая все выходные данные из пакетных файлов.

Совет

Окно списка ошибок ограничено отображением только одной строки выхода — это первая строка, которую вы ввели для события. Если выходные данные окна списка ошибок являются важными для вас, избегайте помещать более одной строки в событие. Создайте пакетный файл из командной строки Windows или в операционной системе, а затем просто используйте call mybatchfile.bat для события. Включите команды в сам пакетный файл.

Для получения инструкций по командам, которые можно использовать в пакетных файлах, см. команды Windows.

Макросы

Обычно доступные "макросы" (фактически свойства MSBuild) перечислены в общие свойства MSBuild. Для проектов SDK для .NET (.NET Core или .NET 5 и более поздних версий) дополнительные свойства перечислены в свойства MSBuild для Microsoft.NET.Sdk.

В сценариях для событий сборки может потребоваться ссылаться на значения некоторых переменных уровня проекта, таких как имя проекта или расположение выходной папки. В предыдущих версиях Visual Studio они назывались макросы. Эквивалент макросов в последних версиях Visual Studio — это свойства MSBuild. MSBuild — это обработчик сборки, который Visual Studio использует для обработки файла проекта при выполнении сборки. Событие сборки в среде IDE приводит к целевой MSBuild в файле проекта. Вы можете использовать любое свойство MSBuild, доступное в целевом файле проекта (например, $(OutDir) или $(Configuration)). Свойства MSBuild, доступные для вас в этих событиях, зависят от файлов, неявно или явно импортированных в файл проекта, таких как .props и .targets файлы, а также свойства, заданные в файле проекта, например в элементах PropertyGroup. Будьте осторожны и используйте точное написание каждого свойства. Ошибка не отображается, если вы неверно написали название свойства; вместо этого неопределенное свойство вычисляется как пустая строка.

Например, предположим, что необходимо указать событие предварительной сборки следующим образом:

Это событие предварительной сборки приводит к следующей записи, называемой Target в файле проекта:

  <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>

Событие сборки появляется как цель, включающая задачу Exec с входными данными, которые вы указали в качестве Command. Новые линии кодируются в ФОРМАТЕ XML.

При сборке проекта в этом примере событие предварительной сборки выводит значения некоторых свойств. В этом примере $(CscToolPath) не создает выходные данные, так как он не определен. Это необязательное свойство, которое можно определить в файле проекта, чтобы предоставить путь к настроенному экземпляру компилятора C# (например, если вы тестировали другую версию csc.exeили экспериментальный компилятор).

Результаты ваших событий сборки записываются в вывод сборки, который можно найти в окне Output. В раскрывающемся списке Показать выходные данные выберите сборки.

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

Заметка

Для некоторых сценариев требуются более сложные действия сборки, чем могут предоставить события сборки. Например, для многих распространенных сценариев создания кода необходимо обрабатывать операции очистки и перестроения, и может потребоваться включить добавочную сборку для шагов создания кода, чтобы этот шаг выполнялось только в том случае, если выходные данные устарели в отношении входных данных. MSBuild предназначен для интеллектуальной обработки всех этих сценариев. Рассмотрите возможность создания пользовательского целевого, указывающего AfterTargets или BeforeTargets для выполнения во время определенной точки в процессе сборки, а также для дальнейшего управления в сложных сценариях, рассмотрите возможность создания пользовательской задачиили просмотрите различные способы настроить сборку.

Пример

1. Создайте пакетный файл с именем postbuild.bat в папке проекта со следующим содержимым:

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

   Помните, что в пакетном файле %1 ссылается на первый аргумент, переданный в.

2. Вызовите пакетный файл в разделе "Событие после сборки" в свойствах проекта и передайте аргумент, используя свойство MSBuild $(TargetPath).

   call postbuild.bat $(TargetPath)
   

3. Создайте проект и проверьте выходную папку. Вы должны увидеть скопированный файл рядом со скомпилированной сборкой. В окне выводав разделе Сборка вы увидите выходные данные пакетного файла:

   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 ==========
   

Связанное содержимое

• страница "События сборки", конструктор проектов (C#)
• диалоговое окно командной строки события предварительной сборки или командной строки события после сборки
• Практическое руководство: Указание событий сборки (Visual Basic)
• Компиляция и сборка