Documentation

Documentation

PostSharp comes with a great user documentation and class reference, not counting scientific articles and community-contributed tutorials. Check the resources below:

Getting Started

Reference Documentation

  • Online documentation: a complete conceptual and reference documentation. This documentation is also installed on your computer and integrated with Visual Studio when you install PostSharp.
  • Scientific publication (PDF): a formal description of PostSharp presented at the scientific conference AOSD 2008 and published in the proceedings of the industry tracks.

Aspects in General

Contributed Tutorials

Other Resources

Architecture

Architecture

PostSharp is designed as an extensible platform for post-processing of .NET assemblies. All analysis and transformations are encapsulated into tasks, which are packaged into plug-ins and loaded in the platform. This platform is named PostSharp Core, while we group under the term PostSharp all the members of this product family.

Most of people use existing plug-ins, like PostSharp Laos. They do not need any extensive knowledge of PostSharp Core and MSIL. If you have more specific requirements, or if you are an Independent Software Vendor producing development tools, you may want to develop your own plug-ins, or even to integrate the platform into your existing tools.

PostSharp Architecture

PostSharp Core

PostSharp Core is the naked platform, coming with no high-level functionality for the end-user. However, it offers a comprehensive and reliable infrastructure on which any assembly post-processing application can rely.

PostSharp Core is made of the following components:

  • The Code Object Model represents with high precision and fidelity any assembly of .NET 2.0, 3.0 or 3.5. It offers high usability and performance. Among useful features of this component: cross-module binding, System.Reflection binding, complex indexing, custom tagging. The Code Object Model is the most fundamental component of PostSharp Core.
  • The Module Reader and Module Writer are responsible for parsing binary assemblies into the Code Object Model and writing them back to binary form.
  • The Low-Level Code Weaver allows injection of MSIL instructions into existing methods. It performs the demanding task of detecting join points and restructuring existing instructions. It serves as a base for weavers of higher level like Laos, while allowing many high-level weavers to coexist peacefully when applied on the same assembly.
  • The Platform Infrastructure manages the whole post-compilation process. It resolves tasks dependencies, load plug-ins on demand, and execute tasks in the proper order. Tasks can be included explicitly in projects by users, or they can be automatically detected during the post-compilation process.

Extension Points

There are typically three ways to develop for PostSharp: writing plug-ins, using PostSharp as a class library, or bootstrapping the platform infrastructure.

Writing Plug-Ins

This is what you will probably do if you need to offer a functionality that cannot be implemented with full satisfaction by other plug-ins.

Plug-ins can use all functionalities of PostSharp Core and of any other plug-in; therefore, you can focus on the real added value of your component, and let infrastructure concerns up to PostSharp.

Plug-ins are sets of tasks, whose dependencies are described in the plug-in manifest.

PostSharp Laos is a good example of plug-in offering added-value features over PostSharp Core.

Using PostSharp As a Class Library

If you don't need the burden of the Platform Infrastructure, but still want to use PostSharp Core, you can use it as a class library. Most functionalities are available even without the Platform Infrastructure.

For instance, you can develop a Reflector-like decompiler based on PostSharp Core.

Bootstrapping the Platform Infrastructure

PostSharp comes with three bootstrappers (or hosts): the MSBuild task, the nant task, and the command-line utility.

If you need to embed assembly-transformation capability in your application, you should consider to host the PostSharp Platform Infrastructure. This is the case, for instance, if you develop an application server.

Benefits

Benefits

Why would you want to add another tool in the already-complex development environment of your team? The ultimate reason is: it will reduce development and maintenance cost of your applications. Let's see how.

Less of Lines of Code

Every line of code is a source of complexity and a potential source of problem. Every line of code costs money. Therefore, every line of code that does not contribute directly to the core concern of the program should be considered with great attention.

Non-functional requirements like transaction management, tracing, security, and exception handling, rarely add business value to the program. They are nevertheless important, since unreliable programs are of no business value at all.

As they are typically implemented by the repetition of the same pattern for the dozens and dozens of methods to which they apply, non-functional requirements generally result in numerous lines of codes.

With aspect-oriented programming, you can address non-functional requirements declaratively and simply remove these bad and expensive lines from your code.

Better Design

The problem with non-functional requirements is that their implementation is mangled in all methods implementing functional requirements. This severely violates the established principle of separation of concerns. With aspect-oriented programming, you could:

  • Improve feature localization: the implementation of transaction handling will be located in the transaction handling aspect, not in every business method.
  • Reduce component coupling: business code will not be directly coupled to the transaction handling implementation any more; it will be easier to change the transaction handler for another.
  • Improve skill set consistency in your team: a domain expert will not have to care about how to implement properly caching in a multithreaded context any more; he will just declare the business method cacheable.

Automate Pattern Implementation

Implementation Patterns are best practices learned by the community through experience. Patterns are often formalized in natural language as 'recipes' giving a solution to a given problem.

Aspect-oriented programming (AOP) makes it possible to encapsulate some of the best practices into executable code: instead of suggesting how to implement correctly exception handling, you may make a custom attribute out of it, and let it available to the team.