PostSharp6.6//Deployment and Configuration/Configuration/Well-Known MSBuild Properties

Well-Known MSBuild Properties

PostSharp recognizes the following 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.

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.

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

PostSharp both reads and executes assemblies it transforms. It needs to run under a runtime that allows execution of the input assembly and of it's dependencies. This is done automatically based on target framework of the currently built project. Following properties allow influencing the default behavior.

Property Name

Description

PostSharpUsePipeServer

Specifies whether PostSharp should use a background process invoked synchronously from MSBuild. Valid values are True and False. 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.

This property is valid only when targetting .NET Framework, otherwise it is ignored.

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.

This property is valid only when targetting .NET Framework, otherwise it is ignored.

PostSharpBuild

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

PostSharpHostConfigurationFile

Item group configuration files containing assembly binding redirections that should be taken into account by the PostSharp hosting process. By default includes app.config and web.config.

PostSharpDependencyRestoreDisabled

Specifies whether PostSharp should disable restore of it's build time dependencies. Valid values are True and False.

PostSharp's .NET Core process requires it's build-time dependency NuGet packages to be present on the machine. By default it uses NuGet restore to download all packages into a fallback directory. You can use this property to disable this process, at which point PostSharp will expect all dependencies to be present in the NuGet package cache directory used to restore the project being built. You can find the list of dependencies in the verbose build log.

This property is valid only when targeting .NET Standard and .NET Core, otherwise it is ignored.

PostSharpReadyToRunDisabled

Specifies whether PostSharp should try to generate and use ReadyToRun images of itself. Valid values are True and False, the default value is False.

When build is running under .NET Core SDK 3.1 and later, PostSharp .NET Core process will attempt to generate and use ReadyToRun images to improve build-time performance. If this generations of these images fails, multiple build warnings may appear in the build log.

This property is valid only when targeting .NET Standard and .NET Core, otherwise it is ignored.

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.

When targeting .NET Framework, PostSharp will invoke [M:System.Diagnostics.Debugger.Launch()]. When targeting .NET Core or .NET Standard, PostSharp will print it's current process ID into the build log and wait for the debugger to be attached.

PostSharpTrace

A semicolon-separated list of trace categories to be enabled. Most commonly used categories are AssemblyBinder, PlatformContext, Domain, ReflectionBinding and ProjectLoader. In order too see the trace output in the build log, at least normal verbosity should be set.

PostSharpBenchmark

A semicolon-separated list of benchmark categories to be enabled or all for all benchmarks to be enabled.

PostSharpBenchmarkOutputFile

An absolute path to CSV file where benchmark data should be appended. If the file does not exist, it is going to be created including header line. This is useful when benchmarking multiple projects at once or in automated builds.

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.

Directory Properties

Property Name

Description

PostSharpBinaryDirectory

Location of the PostSharp binaries. PostSharp extracts it's binaries into one subdirectory of this directory per PostSharp version.

Default on Windows is %PROGRAMDATA%\PostSharp (usually C:\ProgramData\PostSharp). Default on UNIX systems is /var/tmp/postsharp.

PostSharpCacheDirectory

Location of the PostSharp caches. PostSharp uses multiple build-time caches shared between PostSharp versions to improve it's performance.

Default on Windows is %PROGRAMDATA%\PostSharp (usually C:\ProgramData\PostSharp). Default on UNIX systems is /var/tmp/postsharp/cache.

PostSharpDependencyDirectory

Location of the PostSharp dependency directory. PostSharp uses this directory to store it's build time dependencies, usually shared between versions.

Default on Windows is %PROGRAMDATA%\PostSharp\NuGetFallback (usually C:\ProgramData\PostSharp\NuGetFallback). Default on UNIX systems is /var/tmp/postsharp/NuGetFallback.

PostSharpTempDirectory

Location of the PostSharp temp directory. PostSharp uses this directory to store files that are of temporary nature and does not have to be persisted.

Default on Windows is %TEMP%\PostSharp. Default on UNIX systems is /var/tmp/postsharp/temp.

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.