PostSharp has been designed to provide out-of-the-box experience to end-users. If you install PostSharp using the Windows Installer and if you follow the default options, you can start using PostSharp in your projects immediately.

However, if you cannot use the Windows Installer, or if you need per-project flexibility, you can enable or disable PostSharp manually.

Understanding the discovery mechanism

Post-processing an assembly is expensive in CPU time and memory consumption. Therefore, the operation should be performed only when it is needed. But how to know that an assembly needs to be transformed even before analyzing it?

The decision to start PostSharp is taken inside MSBuild based on the list of references of the current project. The first-line rule is simple: if an assembly has references, even indirectly, to PostSharp.Public.dll, MSBuild will invoke PostSharp.

This discovery mechanism is really fast; actually, MSBuild already inspects the list of references in the normal C#/VB build process, so our detection has nearly no overhead.

Therefore, it is not justified not to enable PostSharp globally for performance reasons. There can be other reasons, for instance if you choose to install PostSharp as a dependency of your project, and want to rely on its relative path.

Enabling PostSharp Globally

If you want PostSharp to be inserted in all projects of your machine, you have to do exactly what the installer does: reference PostSharp in documented MSBuild extension points.

You need to do something in every directory that you find on your system in the following list:

In these directories, locate the file Custom.After.Microsoft.Common.targets.

1. If the file Custom.After.Microsoft.Common.targets does not exist, create it

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="Global\Path\To\PostSharp\PostSharp.targets" Condition=" '$(DontImportPostSharp)' != 'True' "/>
</Project>

2. If the file Custom.After.Microsoft.Common.targets exists, just insert the <Import ... /> line in the <Project/> element.

Enabling PostSharp On A Per-Project Basis

If you choose to enable PostSharp on a per-project basis, you need to edit the project file of every project that needs to be post-compiled.

Open the project file (csproj, vbproj, ...)  using a text editor. At the end of the file, there should be one or more <Import .../> elements. For instance, a C# 2.0 project file ends like this:

 <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />

Before the import line, insert the following text:

  <PropertyGroup>
    <DontImportPostSharp>True</DontImportPostSharp>
  </PropertyGroup>

This property is important in case that PostSharp is enabled globally on a machine. It prevents PostSharp global targets to be included in the project when C# or VB targets will be included. Since you can never be sure that PostSharp is not installed globally the machine of another developer working on the same project, it is a good practice to define the DontImportPostSharp before importing main C# / VB targets. Note that it is illegal to import PostSharp targets twice in a project; you will therefore get a build error if you accidently try to do so.

After the C# / VB import line, insert the following text:

<Import Project="Path\To\PostSharp\PostSharp.targets" />

How to determine the path to PostSharp? You have different solutions:

  1. Use an absolute explicit path. It is not a good practice, since the installation path can vary among people working on the same project.
  2. Use the path $(MSBuildExtensionsPath)\PostSharp\PostSharp-1.0.targets. This works only if you have installed PostSharp using the Windows Installer, otherwise these files won't be present.
  3. Use the environment variable POSTSHARP10. This environment variable is set by the Windows Installer and we recommend you to do the same if you install PostSharp globally.
  4. Use a relative path.

Disabling PostSharp

It can happen that you have an assembly referencing PostSharp.Public.dll, but that does not need to be processed by PostSharp. This is the case, for instance, when your assembly contains only aspects. Aspects don't need to (and can not) be themselves transformed.

The easiest way to disable PostSharp in a project is to define the compilation symbol (aka constant) SkipPostSharp.

Therefore, it is possible to have a project with many build configurations and enable PostSharp in only some of these.

Using PostSharp without MSBuild

You can call PostSharp from the command line. This would allow you to integrate PostSharp in other build environments than MSBuild.

However, since the MSBuild targets delivered with PostSharp do most the integration job for you, you will have to learn more about PostSharp workings. See the chapter Running the Compile-Time Utility for details.