Post­Sharp Documentation / Deployment and Configuration / Configuration / Configuring Projects Using MSBuild

Configuring Projects Using MSBuild

Most configuration settings of PostSharp can be set as MSBuild properties.

Note Note

The integration of PostSharp with MSBuild is implemented in files PostSharp.tasks and PostSharp.targets. These files define some properties and items that are not documented here. They are considered implementation details and may change without notice.

This topic contains the following sections:

Setting MSBuild properties with a text editor

To set a property that persistently applies to a specific project, but not to the whole solution, the best solution is to define it directly inside the C# or VB project file (*.csproj or *.vbproj, respectively) using a text editor.

Adding a project-level MSBuild property using Visual Studio

  1. Open the Solution Explorer, right-click on the project name, click on Unload project, then right-click again on the same project and click on Edit.

  2. Insert the following XML fragment just before the <Import /> elements:

    <PropertyGroup>
        <PropertyName>PropertyValue</PropertyName>
    </PropertyGroup>

    See Configuring Projects Using MSBuild for the list of MSBuild properties used by PostSharp.

  3. Save the file. If the project was open in Visual Studio, go to the Solution Explorer, right-click on the project name, then click on Reload project.

Note Note

For more information regarding MSBuild properties, see MSDN Documentation.

Configuring several projects at a time

Instead of editing every project file, you can define shared settings in a file named PostSharp.Custom.targets and store in the same directory as the project file or in any parent directory of the parent file (up to 7 levels from the project directory).

Files PostSharp.Custom.targets are loaded from the root directory to the project directory, so that files that are closer to the project directory are loaded after and override files in parent directories.

Thanks to this mechanism, it is possible to define settings that apply to a large set of projects and control the grain of settings.

Files PostSharp.Custom.targets are normal MSBuild project or targets files; they should have the following content:

<? xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <PropertyName>PropertyValue</PropertyName>
  </PropertyGroup>
</Project>

See Configuring Projects Using MSBuild for the list of MSBuild properties used by PostSharp.

Note Note

For more information regarding MSBuild project files, see MSDN Documentation.

Setting MSBuild properties from the command line

When an MSBuild property does not need to be set permanently, it is convenient to set is from the command prompt by appending the flag /p:PropertyName=PropertyValue to the command line of msbuild.exe, for instance:

msbuild.exe /p:PostSharpHost=Native
List of properties

General Properties

The following properties are most commonly overwritten. They can also be edited in Visual Studio using the PostSharp project property page.

Property Name

Description

PostSharpSearchPath

A semicolon-separated list of directories added to the PostSharp search path. PostSharp will probe these directories when looking for an assembly or an add-in. Note that several directories are automatically added to the search path: the .NET Framework reference directory, the directories containing the dependencies of your project and the directories added to the reference path of your project (tab Reference Path in the Visual Studio project properties dialog box).

SkipPostSharp

True if PostSharp should not be executed.

PostSharpOptimizationMode

When set to OptimizeForBuildTime, PostSharp will use a faster algorithm to generate the final assembly. The other possible value is OptimizeForSize. The default value of the PostSharpOptimizationMode property is OptimizeForBuildTime by default and OptimizeForSize when the C# or VB compiler is set to generate optimal code (typically, in release builds).

PostSharpDisabledMessages

Comma-separated list of warnings and messages that should be ignored.

PostSharpEscalatedMessages

Comma-separated list of warnings that should be escalated to errors. Use * to escalate all warnings.

PostSharpLicense

License key or URL of the license server.

PostSharpProperties

Additional properties passed to the PostSharp project, in format Name1=Value1;Name2=Value2. See Well-Known PostSharp Properties.

PostSharpConstraintVerificationEnabled

Determines whether verification of architecture constraints is enabled. The default value is True.

Hosting Properties

Because PostSharp not only reads but also executes the assemblies it transforms, it must run under the proper version and processor architecture of the CLR. Additionally, for each version and processor architecture. The following properties allow influencing the choice of the PostSharp host process.

Property Name

Description

PostSharpTargetFrameworkVersion

Version of the CLR that hosts the PostSharp process. The only valid value is 4.0.

PostSharpTargetProcessor

Processor architecture of the PostSharp hosting process. Valid values are x86 and x64. Since PostSharp needs to execute the current project during the build, the processor architecture of the PostSharp process must be compatible with the target platform of the current project. The default value is x86, or x64 if the target platform of the current project is x64.

PostSharpHost

Kind of process hosting PostSharp. This setting is usually changed for troubleshooting only. The following values are supported:

  • PipeServer means that PostSharp will run as a background process invoked synchronously from MSBuild. Using the pipe server results in lower build time, since PostSharp would otherwise have to be started every time a project is built. The pipe server uses native code and the CLR Hosting API to control the way assemblies are loaded in application domains; the assembly loading algorithm is generally more accurate and predictable than with the managed host.

  • Native uses the same native code as the pipe server, but the process runs synchronously and terminates immediately after an assembly has been processed. For this reason, it does not have the same build-time performance as the pipe server, but it has exactly the same assembly loading algorithm and is useful for diagnostics.

  • Managed is a purely managed application. The assembly loading algorithm may be less reliable in some situations because PostSharp has less control over it. Note that this host is no longer being tested and officially supported.

PostSharpBuild

Build configuration of PostSharp. Valid values are Release, Diag and Debug. Only the Release build is distributed in the normal PostSharp packages.

PostSharpHostConfigurationFile

A semicolon-separated list of configuration files containing assembly binding redirections that should be taken into account by the PostSharp hosting process, such as app.config or web.config.

Diagnostic Properties

Property Name

Description

PostSharpAttachDebugger

If this property is set to True, PostSharp will break before starting execution, allowing you to attach a debugger to the PostSharp process. The default value is False. For details, see Debugging Build-Time Logic.

PostSharpTrace

A semicolon-separated list of trace categories to be enabled. The property is effective only when PostSharp runs in diagnostic mode (see property PostSharpBuild here above). Additionally, the MSBuild verbosity should be set to detailed at least. For details, see Debugging Build-Time Logic.

PostSharpUpdateCheckDisabled

True if the periodic update check mechanism should be disabled, False otherwise.

PostSharpExpectedMessages

A semicolon-separated list of codes of expected messages. PostSharp will return a failure code if any expected message was not emitted. This property is used in unit tests of aspects, to ensure that the application of an aspect results in the expected error message.

PostSharpIgnoreError

If this property is set to True, the PostSharp MSBuild task will succeed even if PostSharp returns an error code, allowing the build process to continue. The project or targets file can check the value of the ExitCode output property of the PostSharp MSBuild task to take action.

PostSharpFailOnUnexpectedMessage

This property should be used jointly with PostSharpExpectedMessages. If it set to True, PostSharp will fail if any unexpected message was emitted, even if this message was not an error. This property is used in unit tests of aspects, to ensure that the application of an aspect did not result in other messages than expected.

Other Properties

Property Name

Description

PostSharpProject

Location of the PostSharp project (*.psproj) to be executed by PostSharp, or the string None to specify that PostSharp should not be invoked. If this property is defined, the standard detection mechanism based on references to the PostSharp.dll is disabled.

PostSharpUseHardLink

Use hard links instead of file copies when creating the snapshot for Visual Studio Code Analysis (FxCop). This property is True by default.

ExecuteCodeAnalysisOnPostSharpOutput

When set to True, executes Microsoft Code Analysis on the output of PostSharp. By default, the analysis is done on the input of PostSharp, i.e. on the output of the compiler. This property has no effect when Microsoft Code Analysis is disabled for the current build.

PostSharpCopyCodeAnalysisDependenciesDisabled

When set to True, PostSharp will not copy the all dependencies of the current project output into the obj\Debug\Before-PostSharp directory, which contains the copy of the assembly on which Microsoft Code Analysis is executed by default. This property has no effect when Microsoft Code Analysis is disabled for the current build or when the ExecuteCodeAnalysisOnPostSharpOutput property has been set to True.