PostSharp6.5//Deployment and Configuration/Configuration/Configuring Projects Using postsharp.​config

Configuring Projects Using postsharp.config

You can configure PostSharp by putting an XML file named postsharp.config in your project directory or in any parent directory. This configuration file can also be named <YourProject>.psproj or <YourProject>.pssln as we will describe here below.

This topic contains the following sections:

When to use a configuration file?

Configuration files are typically useful in the following scenarios:

  • Adding a license key to your source code:

    XML
    <?xml version="1.0" encoding="utf-8"?>
    <Project xmlns="http://schemas.postsharp.org/1.0/configuration">
      <License Value="000-AAAAAAAAAAAAAAA"/>
    </Project>
  • Configuring the build-time options of features like logging, for instance:

    XML
    <?xml version="1.0" encoding="utf-8"?>
    <Project xmlns="http://schemas.postsharp.org/1.0/configuration">
      <Logging xmlns="clr-namespace:PostSharp.Patterns.Diagnostics;assembly:PostSharp.Patterns.Diagnostics">
        <Profiles>
          <LoggingProfile Name="detailed" IncludeSourceLineInfo="True" IncludeExecutionTime="True" IncludeAwaitedTask="True">
            <DefaultOptions>
              <LoggingOptions IncludeParameterType="True" IncludeThisValue="True"/>
            </DefaultOptions>
          </LoggingProfile>
        </Profiles>
      </Logging>
    </Project>

    See Customizing the Appearance of Log Records for details.

  • Adding aspects to your code without affecting your code base, for instance:

    XML
    <Project xmlns="http://schemas.postsharp.org/1.0/configuration">
      <Multicast>
        <LogAttribute xmlns="clr-namespace:PostSharp.Patterns.Diagnostics;assembly:PostSharp.Patterns.Diagnostics"
                      AttributeTargetTypes="PostSharp.Patterns.Diagnostics.Tests.NLog.Person" />
      </Multicast>
    </Project>

    See Adding Aspects Using XML for details.

Other less common use cases are:

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

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

Configuration file schema
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. This is the recommended way to configure new projects.

  2. Any file named <MySolution>.pssln located in the same directory as the solution file <MySolution>.pssln. Also PostSharp Tools for Visual Studio uses this file for convenience, we recommend you do not use this file and move the configuration to a shared postsharp.config file instead. The reason is that a project file can belong to several solutions, and it would be misleading to have the compilation depend on which solution was used.

  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.

Sharing configuration between projects

The most typical way to share configuration between projects is to have a postsharp.config file in a parent directory of all projects.

Additionally, it is possible to define a Using configuration element:

XML
<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.postsharp.org/1.0/configuration">
   <Using File="..\LoggingProfiles.config"/>
</Project>