New in PostSharp 4.3 Preview: Command-Line Interface

It is now possible to bypass NuGet and MSBuild integration and invoke PostSharp as an executable. This feature was supported up to PostSharp 2.1 and then removed in PostSharp 3. We are including it back because of popular demand.

Why to use the command-line interface?

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 like logging, the situation is different. It is perfectly valid to add logging to an existing assembly. In this case, MSBuild is not the good option.

You can use the command-line interface in the following situations:

1. When you have access to the source code of a project but you don’t want to add instrumentation into the normal C#/VB project file, but as a separate step.
2. When you don’t have access to the source code of the assembly you want to instrument. (Legal disclaimer: in this case, make sure your license allows you to modify the assembly)

Example: instrumenting DotNetty

To demonstrate a typical use of the command-line, let’s take some random open-source project: DotNetty, a network stack used by the Azure platform. To keep the example simple, let’s add logging to the Echo.Client assembly.

Step 1. Download and extract the ZIP distribution

If you want to run PostSharp as a stand-alone executable, you will likely prefer to download the zip distribution of PostSharp instead of the NuGet packages. The zip distributions is one of the good things of PostSharp 2.1 that disappeared in PostSharp 3 and that we are bringing back. To download the zip distribution, go to https://www.postsharp.net/downloads/postsharp-4.3, then download the file named PostSharp-<version>.zip and extract it to your local machine.

Step 2. Create a PostSharp project file

Create a file named postsharp.config (any file name will work) and add the following content:

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

  <Property Name="Input" Value="Echo.Client.exe" />
  <Property Name="Output" Value="Echo.Client2.exe" />
  <Property Name="LoggingBackend" Value="Console" />

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

</Project>

Note that you can add any aspect to the assembly using this project file. For details, see our documentation.

Step 3. Invoke PostSharp

PostSharp executables are located under the tools folder. There are a lot of files in this directory, but you should focus on two: postsharp-net40-x64-native.exe and postsharp-net40-x86-native.exe. Use the first executable to transform x64 projects and the second to transform anything else.

Type the following command:

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

Step 4. Run the instrumented program

First, copy file Echo.Client.exe.config to Echo.Client2.exe.config so that the new executable will find its configuration.

Then execute Echo.Client2.exe and… enjoy the logging!

Summary

With PostSharp 4.3, we are bringing back a few good features of PostSharp 2.1 that disappeared in PostSharp 3: the zip distribution and the command-line executable.

You can use the command-line executable whenever you want to add instrumentation to an assembly without having to recompile it – whether or not you have its source code.

Is it useful for your scenario? How can we improve? Please let us know!

Happy PostSharping,

-gael

P.S. This post is the first in a series dedicated to the new features of PostSharp 4.3:

1. Command-Line Interface;
2. Improved Debugging Experience;
3. Alternative to NuGet deployment.