8.4. MSBuild Integration

8.4.1. Overview

Microsoft Build Engine, widely known as MSBuild, is a platform for building applications. It can be used directly to build a project, and runs behind the scenes when you are working inside an IDE, such as Microsoft Visual Studio.

Each MSBuild project is defined by an XML file which describes how the software should be built.

One of the great sides of MSBuild is that it allows to extend the build process via the project file. Eazfuscator.NET uses this integration mechanism to enable obfuscation during the build. Depending on the scenario, Eazfuscator.NET can apply different methods of integration when protecting a project. These methods are explained below.

8.4.2. Post-build Event Integration

The post-build event scenario may be familiar to you from Microsoft Visual Studio:

The commands specified in the post-build event section are executed after the build is finished. The picture above shows a post-build event command line that runs Eazfuscator.NET with several parameters when the project configuration is set to Release. The command can be easily tweaked using Eazfuscator.NET command-line interface.

For some time, Eazfuscator.NET had been using the post-build event integration exclusively. It was simple and worked perfectly. However, new project types emerged later: VSIX, UWP, and all the SDK-style projects. These projects had different build pipelines and required Eazfuscator.NET to kick in the middle of a build process. In order to meet more sophisticated and complex scenarios, a new integration at MSBuild level was introduced.

8.4.3. MSBuild-level Integration

Integration at MSBuild level makes obfuscation a full-fledged part of a build pipeline. It provides great control over the whole process, and thus enables seamless processing even in complex scenarios.

Here, the post-build event is not used anymore, so a corresponding hint is embedded:

Let's see how an MSBuild-level integration looks like in the project file when done by Eazfuscator.NET:

<Project Sdk="Microsoft.NET.Sdk">
        
  <Import Condition=" '$(EAZFUSCATOR_NET_HOME)' != '' and Exists('$(EAZFUSCATOR_NET_HOME)\Integration\MSBuild\Eazfuscator.NET.targets') " Project="$(EAZFUSCATOR_NET_HOME)\Integration\MSBuild\Eazfuscator.NET.targets" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup>
    <EazfuscatorIntegration>MSBuild</EazfuscatorIntegration>
    <EazfuscatorActiveConfiguration>Release</EazfuscatorActiveConfiguration>
    <EazfuscatorCompatibilityVersion>2022.1</EazfuscatorCompatibilityVersion>
  </PropertyGroup>

</Project>

	The import directive instructs MSBuild to import Eazfuscator.NET targets.
	A group of Eazfuscator.NET MSBuild properties configures the obfuscation integration.

MSBuild properties related to Eazfuscator.NET are described in the table below.

Table 8.1. Available MSBuild properties for use with Eazfuscator.NET

Property	Description
EazfuscatorIntegration	Specifies Eazfuscator.NET integration mode. The value should always be set to MSBuild for MSBuild-level integration
EazfuscatorActiveConfiguration	A project configuration Eazfuscator.NET works at. The default value is Release
EazfuscatorActiveConfigurations	A set of project configurations Eazfuscator.NET works at, separated by a semicolon. This property is only honored when EazfuscatorActiveConfiguration property is not set
EazfuscatorCompatibilityVersion	A version of Eazfuscator.NET to be compatible with. This property is equivalent to -v [ --compatibility-version ] command-line option
EazfuscatorExtraArgs	Additional command-line options to be passed to Eazfuscator.NET. The following options cannot be used with this property as they are inferred automatically: --msbuild-project-path, --msbuild-project-configuration, --msbuild-project-platform, --msbuild-solution-path. The option -v [ --compatibility-version ] cannot be specified either; please use EazfuscatorCompatibilityVersion MSBuild property instead

Example

Let's say we want Eazfuscator.NET to work at two build configurations, Release and ReleaseEx, and also have obfuscation statistics report (-s option) printed out. Here is how obfuscation MSBuild properties in our project would look like to reach those goals:

<PropertyGroup>
  <EazfuscatorIntegration>MSBuild</EazfuscatorIntegration>
  <EazfuscatorActiveConfigurations>Release;ReleaseEx</EazfuscatorActiveConfigurations>
  <EazfuscatorCompatibilityVersion>2022.1</EazfuscatorCompatibilityVersion>
  <EazfuscatorExtraArgs>-s</EazfuscatorExtraArgs>	
</PropertyGroup>