Executing PostSharp from the Command Line

You can execute PostSharp from the command line whenever you want to instrument an existing assembly – whether or not you have the source code of that assembly.

PostSharp has been primarily designed as an extension to the C# and VB languages that automates the implementation or validation of patterns. Most patterns need to be present for the application to work. Think for instance of INotifyPropertyChanged. It does not make sense to have a build of your application that does not implement INotifyPropertyChanged. Therefore, the best way to invoke PostSharp is to use the default MSBuild integration.

However, if you think of instrumentation aspects such as logging, tracing, performance measurement, then the situation is different. It is perfectly valid to add logging to an existing assembly. In this case executing PostSharp from the command line may be your best option.

In general, you can use the command-line interface in the following situations:

  • When you have access to the source code of a project and you want to add instrumentation as a separate step, instead of using the normal C#/VB project file.

  • When you don’t have access to the source code of the assembly you want to instrument. In this case, make sure your license allows you to modify the assembly.

Instrumenting assembly from the command line

To instrument assembly from the command line:

  1. Download and extract PostSharp ZIP distribution.

    1. Go to https://www.postsharp.net/downloads/.

    2. Choose the desired version of PostSharp (only 4.3 or later).

    3. Download the file named PostSharp-<version>.zip and extract it on your local machine.

  2. Create a PostSharp configuration file for your project (see Working with PostSharp Configuration Files). These are the most common items to specify in the configuration file:

    • Set the Input property to the file path of the input assembly (relative to the project file location).

    • Set the Output property to the file path of the output assembly (relative to the project file location).

    • Declare the aspects that you want to apply to your assembly (see Adding Aspects Using XML).

    • Add the SearchPath element to specify where PostSharp should look for assemblies and plug-ins (in addition to PostSharp package directory and input assembly directory).

    Example 1. Instrumenting assembly with the PostSharp logging aspect.

    <Project xmlns="http://schemas.postsharp.org/1.0/configuration">
      <Property Name="Input" Value="MyAssembly.dll" />
      <Property Name="Output" Value="MyAssembly.Instrumented.dll" />
      <Property Name="LoggingBackend" Value="Console" />
      <Multicast>
        <LogAttribute xmlns="clr-namespace:PostSharp.Patterns.Diagnostics;assembly:PostSharp.Patterns.Diagnostics" />
      </Multicast>
    </Project>

    Example 2. Instrumenting assembly with a custom aspect.

    <Project xmlns="http://schemas.postsharp.org/1.0/configuration">
      <Property Name="Input" Value="MyAssembly.dll" />
      <Property Name="Output" Value="MyAssembly.Instrumented.dll" />
      <SearchPath Path="C:\Path\MyAspects" />
      <Multicast>
        <ProfileAttribute xmlns="clr-namespace:MyAspects;assembly:MyAspects" />
      </Multicast>
    </Project>
  3. Invoke PostSharp. PostSharp executables are located under the tools folder of the extracted archive. You can choose between these two executables:

    • postsharp-net40-x64-native.exe – use to transform x64 assemblies.

    • postsharp-net40-x86-native.exe – use to transform any other assemblies.

    To apply the transformation to your project, invoke the PostSharp executable and specify the path to the project configuration file as a command line argument. For example:

    c:\PostSharp\tools\postsharp-net40-x86-native.exe postsharp.config

    Upon completing the instrumentation of your assembly, PostSharp will output the “complete” message with the PostSharp version number and total numbers of errors and warnings, if any.

    PostSharp 4.3 [4.3.x.0, postsharp-net40-x86-native.exe, CLR 4.0.30319.394254, Release] complete -- 0 errors, 2 warnings, processed in 1000 ms

    You can also specify the input assembly as a command line argument. In this case PostSharp recognizes the argument type based on the file name extension (e.g. *.config, *.pssln, *.psproj for project files, *.exe, *.dll for input assemblies). The input assembly specified on the command line overrides the corresponding Input property in the project file.

    c:\PostSharp\tools\postsharp-net40-x86-native.exe postsharp.config MyAssembly.dll

By following the steps outlined in this article, you add instrumentation to an existing assembly without having to recompile it from the source code.

See Also