This is the online documentation for PostSharp 5.0.
Download PDF or CHM. Go to v4.3 or v5.0

Working with PostSharp Configuration Files

PostSharp is designed as a modular post-compilation platform, whose functionality can be extended using plug-ins. For instance, the Diagnostics Pattern Library is implemented as a plug-in. Although writing custom plug-ins is out of scope of this documentation, you should be able, as a PostSharp user, to understand how plug-ins can be added to a project and how they can be configured.

This topic contains the following sections:

PostSharp configuration files

The configuration system of PostSharp is based on configuration files.

By default, if you have a project named MyProject.csproj, PostSharp will try to load, from the same directory, a configuration file, named MyProject.psproj. Configuration file is optional. Most projects don't need it.

See Configuration File Schema Reference for details about the format of this file.

For instance, the following code is the configuration file of a project using two plug-ins:

<Project xmlns="http://schemas.postsharp.org/1.0/configuration">

  <Property Name="LoggingBackend" Value="nlog" />

  <Using File="..\..\Build\bin\{$Configuration}\PostSharp.Patterns.Diagnostics.Weaver.dll"/>
  <Using File="..\..\Build\bin\{$Configuration}\PostSharp.Patterns.Diagnostics.Weaver.NLog.dll"/>

  <Multicast>
    <LogAttribute xmlns="clr-namespace:PostSharp.Patterns.Diagnostics;assembly:PostSharp.Patterns.Diagnostics"
                  AttributeTargetTypes="PostSharp.Patterns.Diagnostics.Tests.NLog.Person" />
  </Multicast>

</Project>

The principal use cases for end-users are the following:

  • Adding license keys. See the License configuration element for details.

  • Configuring properties. See the Property configuration element for details.

  • Including a plug-in. See the Using configuration element for details.

  • Adding aspects or constraints without modifying source code. See Adding Aspects Using XML for details.

  • Editing logging profiles. See Configuration File Schema Reference and [logging-profiles] for details.

Sharing configuration between projects

You will often want to share some configuration settings between several projects. A typical example is to add the license key to all projects of your source code repository.

This can be achieved by adding a well-known configuration file to your source tree, or thanks to the Using configuration element.

Well-known configuration files

PostSharp will automatically load a few well-known configuration files if they are present on the file system, in the following order:

  1. Any file named postsharp.config located in the directory containing the MSBuild project file (csproj or vbproj, typically), or in any parent directory, up to the root. These files are loaded in ascending order, i.e. up from the root directory to the project directory.

  2. Any file named MySolution.pssln located in the same directory as the solution file MySolution.sln .

  3. Any file named MyProject.psproj located in the same directory as the project file MyProject.csproj or MyProject.vbproj .

For instance, the files may be loaded in the following order:

  1. c:\src\BlueGray\postsharp.config

  2. c:\src\BlueGray\FrontEnd\postsharp.config

  3. c:\src\BlueGray\FrontEnd\BlueGray.FrontEnd.Web\postsharp.config

  4. c:\src\BlueGray\Solutions\BlueGray.pssln assuming that the current solution file is c:\src\BlueGray\Solutions\BlueGray.sln.

  5. c:\src\BlueGray\FrontEnd\BlueGray.FrontEnd.Web\BlueGray.FrontEnd.Web.psproj assuming that the current project file is c:\src\BlueGray\Solutions\BlueGray.sln.

Explicit configuration sharing

The second technique to share a configuration file among several projects is to use the Using configuration element to import a configuration file into another configuration file.

Order of processing of configuration files

Elements of configuration files are processed in the following order:

  1. License elements are loaded.

  2. Property elements are loaded. Properties are evaluated at this moment, unless they are marked for deferred evaluation.

  3. SearchPath elements are loaded.

  4. Using elements are loaded and referenced plug-ins and configuration files are immediately loaded.

  5. SectionType elements are loaded.

  6. Service elements are loaded, but they are not yet instantiated.

  7. Extension elements are loaded, but they are not evaluated at this moment.

  8. Finally, services and other tasks are instantiated and the project is executed.