PostSharp Official Blog

Webinar: How to Stay DRY with AOP and PostSharp – with Video and Q&A!

Gael Fraiteur — Fri, 27 Jan 2012 05:20:47 PST

Wow! What a turnout for my first webinar! Thank you all for attending, I had a great time presenting it, and will continue to do more webinars in the future. The webinar was recorded, and the video is now online for your viewing:

As promised, here are the answers to the great questions you asked, which I didn’t have the chance to answer during the live webinar. As always, you can always ask your questions on our Support Forums.

Q: Any reason the [aspect] class must be Serializable?

A: At (post) compilation, the aspect is serialized using binary serialization, and added as a resource to the target process. Then at runtime, the aspect is deserialized. PostSharp will emit a compilation error if you forget to mark your aspect as Serializable.

Q: What is the typical use case for creating interfaces using PostSharp?

A: One typical scenario for implementing interfaces with PostSharp is implementing INotifyPropertyChanged in WPF to support Data Binding.

Q: Are the OnExit and OnEnter aspects thread safe? How would one make it thread safe if it is not?

A: While the aspects themselves are thread-safe, shared state (i.e. custom fields) within the aspects is not. To safely pass data around between OnEnter and OnExit events, you can use the MethodExecutionArgs.MethodExecutionTag property.

Q: What about signed DLLs and PostSharp?

A: PostSharp has no problems with signed DLLs – they will be re-signed after the post-compilation process.

Q: What about Silverlight DLL's, is it also available?

A: Of course, PostSharp comes with the Silverlight assemblies included, you need to add a reference to the PostSharp.SL.dll instead of PostSharp.dll. For more information, please refer to the online documentation.

Q: Can you provide a good definition of aspect oriented programming?

A: Aspect Oriented Programming complements traditional OOP by allowing us to encapsulate infrastructure code (such as logging, security, validation, etc.) into small modules called aspects, and then apply those aspects throughout the entire system in such way that the business logic is completely separated from those concerns.

So go ahead, download the free starter edition now!

Happy PostSharping!

-Igal

Live Webinar: How to Stay DRY with AOP and PostSharp

Igal Tabachnik — Tue, 17 Jan 2012 08:46:09 PST

Boilerplate code. It’s all around us, polluting our business logic, and forcing us to write the same code over and over again. Join us on Thursday, January 26th, as our very own Igal Tabachnik shows you how to stay DRY (Don’t-Repeat-Yourself) by using aspect-oriented programming (AOP) and PostSharp to remove boilerplate code that’s duplicated in and across systems.

Attendees will learn:

Why the DRY principle matters
How AOP helps to remove boilerplate code
How to use PostSharp to produce cleaner code
Real-world AOP usage examples

Oh, and that’s not all – we’re giving away two PostSharp licenses to two lucky attendees!

So hurry up, sign up here: https://www3.gotomeeting.com/register/724468246

Feature Focus: Showing message locations in the source code

Igal Tabachnik — Wed, 04 Jan 2012 08:13:00 PST

During compilation, PostSharp takes great care in making sure that everything works correctly. When something goes wrong, PostSharp will report it as an error or a warning. Until now, however, whenever an error or a warning occurred, the developer had to manually navigate to that place in code.

We are excited to announce that with PostSharp 2.1 we’ve enhanced the errors and warnings with the exact location information, allowing you to simply double-click on the message and you’ll be taken to the error line!

To enable this feature, go to Tools – Options – PostSharp, and under Experimental, set Resolve Message Location to True:

Then, simply rebuild your solution, and if there are any warnings or errors, you’ll be able to see exactly where they are:

This is accomplished by specifying the member (in this case, the method) that is responsible for the message, in the aspect’s CompieTimeValidate method:

// Validate the attribute usage.
public override bool CompileTimeValidate( MethodBase method )
{
    // Don't apply to constructors.
    if ( method is ConstructorInfo )
    {
        Message.Write( method, SeverityType.Error, "CX0001", 
                       "Cannot cache constructors." );
        return false;
    }

    MethodInfo methodInfo = (MethodInfo) method;

    // Don't apply to void methods.
    if ( methodInfo.ReturnType.Name == "Void" )
    {
        Message.Write( method, SeverityType.Error, "CX0002", 
                       "Cannot cache void methods." );
        return false;
    }

    // Does not support out parameters.
    ParameterInfo[] parameters = method.GetParameters();
    for ( int i = 0; i < parameters.Length; i++ )
    {
        if ( parameters[i].IsOut )
        {
            Message.Write( method, SeverityType.Error, "CX0003", 
                           "Cannot cache methods with return values." );
            return false;
        }
    }

    return true;
}

Aspect developers are encouraged to include the member in error/warning messages. For more information, please refer to the documentation on Working with Errors, Warnings and Messages.

Please note that this is not enabled by default as it is still experimental and might have an impact on performance. Please let us know how it works out for you!

Happy PostSharping!

-Igal

Feature Focus: View source code enhanced by PostSharp

Igal Tabachnik — Wed, 21 Dec 2011 11:12:00 PST

As most of you know, PostSharp’s transformation (weaving) of aspects into your assemblies happens after the compilation. One of the most requested features is the ability to see the actual code that is produced by PostSharp. Until now, you had to manually open the newly compiled assembly in your favorite decompiler to see the produced code.

We are delighted to announce that we’ve made viewing the source code in your favorite decompiler much easier – via a single click on the enhanced class or method:

By clicking the See enhanced source code link for the first time, you will be asked to select the decompiler you want to use (we currently support dotPeek, ILSpy and Reflector). You can always change the decompiler later from Tools – Options – PostSharp:

From now on, when you click on the See enhanced source code, your chosen decompiler will open and show you exactly the source code, as it was modified by PostSharp!

This feature is available in the latest version of PostSharp!

Happy PostSharping!

-Igal

Free Course from Donald Belcham on Pluralsight

Britt King — Wed, 21 Dec 2011 06:08:00 PST

If learning more about Aspect Oriented Programming is on your to-do list for 2012, we have some very good news for you.

We’ve teamed up with the good folks at Pluralsight to make it easier than ever for developers to get up to speed on developing with aspects. PostSharp users can sign-up to receive a free 30-day trial membership good towards one Pluralsight online course.

Start learning about Aspect Oriented Programming for .NET today >>

Pluralsight, “the leader in high-quality online training for hardcore developers,” has a huge library of online courses to choose from but, naturally, the course we recommend is Aspect Oriented Programming for .NET by PostSharp MVP and Pluralsight Author, Donald Belcham.

Donald is a senior software developer, independent contractor, author, and trainer based in Edmonton, Canada. He spoke about the topic of Aspect Oriented Programming at NDC and DevTeach Montreal earlier this year, and published the online course on Pluralsight in June.

The course is divided into four parts:

Introduction to AOP
AOP using Interceptors
AOP using IL Code Weaving
AOP beyond decorators

From Donald: “My course is perfect for developers who want to learn how to avoid code repetition by implementing AOP in .NET projects using IL Code Weaving frameworks like PostSharp, Interception frameworks like Castle Windsor, and even how to implement AOP without following the traditional decorator pattern.”

Apply for your free 30-day Pluralsight trial membership today and, upon approval, we’ll email you a unique login code plus a link to a special sign-in page for PostSharp users.

Start your free 30-day trial membership today >>

-Britt

PostSharp Makes Hanselman's 2011 Ultimate Tools List

Britt King — Fri, 02 Dec 2011 05:33:00 PST

Scott Hanselman knows tools.

As a Principle Program Manager at Microsoft, and one of the most sought-after developer speakers on the planet, Scott has his finger planted firmly on the pulse of the .NET community. Luckily for all of us, he only uses his powers for good by entertaining and educating the community about software development across a variety of channels including podcasts, presentation and speaking tips, books, and more.

Since his first ultimate tools list in 2003, the popularity and length of Scott’s annual lists have grown considerably. This year’s list includes categories such as “The Big Ten Life and Work-Changing Utilities,” “Rocking Sweet Windows 7 Specific Stuff,” and “A (.NET) Developer's Life,” to name a few.

We’re thrilled and honored to see PostSharp included in Scott’s 2011 ultimate tools list alongside so many other great tools. We know we wouldn’t have made the list without the help of our customers, MVPs, and partners. Thank you, all.

The ultimate tools list wasn’t our first run-in with Scott in 2011. Gael sat down with him in September as part of his startup podcast series, to discuss the challenges of taking PostSharp from open source to commercial business. The two talked about aspect-oriented programming and Scott rightly pointed out that AOP is another kind of abstraction, which is the whole point of what computers are supposed to do for us, work that’s not fun like logging and transactions.

Since the beginning of 2011 we’ve focused on spreading the word about the benefits of aspect oriented programming for .NET with in-office trainings, user group and conference presentations, podcasts and screencasts, white paper and blog posts.

It seems to be working.

In September, the same month as the Hanselminutes podcast, we announced a rising trend in AOP adoption among developers in large organizations, especially those in the Fortune 500, and created case studies showing how two big companies, Siemens Audiology and Thales Information Systems, are succeeding with PostSharp.

There’s more to come in 2012, and we look forward to speaking with more of you about your experience with PostSharp. Special thanks goes out to Scott Hanselman for his seemingly tireless commitment to the community and his never-ending quest to find the ultimate tools for .NET.

Happy PostSharping!

-Britt

IdeaBlade releases DevForce Code First

Gael Fraiteur — Mon, 07 Nov 2011 13:45:40 PST

I’m thrilled to announce that our partner IdeaBlade has just released a new version of DevForce. This application framework already provided pretty much all of the wiring you need to develop rich line-of-business applications (Silverlight and WPF backed by WCF, Entity Framework, OData). The last release now supports domain models written for Entity Framework in Code First style… and that still respect the spirit of Code First: nice, clean code, free from infrastructure boilerplate.

Guess who is writing that boilerplate for you? Right: PostSharp. What’s nice with DevForce is that you can start coding immediately and don’t have to understand anything about AOP and PostSharp since DevForce provides all the aspects you need. Even better: you don’t need to download PostSharp and you don’t have to check-out any license: all is included in the IdeaBlade package.

See! I managed to avoid the c*c*c word.

I’d like to thank Albert and his team for their efforts and feedback during the RC stage of PostSharp 2.1. I’m sure DevForce and PostSharp will benefit from each other and will make it even easier to develop strong LOB applications.

Happy PostSharping – now even to those who never heard of PostSharp.

-gael

Announcing PostSharp 2.1 RTM

Mon, 31 Oct 2011 04:07:00 PDT

I’m delighted to announce the release of PostSharp 2.1 RTM, available for download on our web site and on NuGet.

The last release candidate has been available as the front-page download for more than a month now with no reported bugs. PostSharp 2.1 becomes the recommended version for everyone and is now considered more stable than the 2.0 branch.

New features

PostSharp 2.1 brings the following improvements to PostSharp 2.0:

Improved build-time performance: up to 5x faster. Read more.
Architecture validation: build-time validation of design rules. Read more.
Extended reflection API: programmatically navigate code references. Read more and more.
NuGet packaging and improved no-setup deployment experience. Read more.
Support for obfuscators: we now support Dotfuscator. Read more.
Improved Visual Studio Extension (PostSharp tab page in project properties).
Warnings and errors now come with file/line information. The feature is optional and must be enabled manually from Visual Studio options. We’re eager to hear feedback about this feature from customers with larger projects.
Support for Silverlight 5 and Windows Phone 7.1.
Compatibility with Code Contracts 4.
Improved messaging API.
Streamlined licensing experience and “getting started”.
License server (optional).
Streamlined “getting started” experience.
Warnings can be disabled locally (for a specific element of code) using the IgnoreWarning custom attribute. See online documentation for details.

Bug fixes

The RTM fixes the following issues from RC2:

"EnhancedByPostSharpAttribute" causes issues with the WPF compiler
Aspected methods with parameter of generic types are not underlined in VS code editor
Constant SkipPostSharp does not work
Different versions of PostSharp cannot be used in the same solution
Error due to file lock of *.vhost.exe
Invalid version number is written in native resources
MSBuild error "CodeContractsPerformCodeAnalysis target is missing" with Code Contracts Standard (without Code Analysis)
Type parser throws exception with arrays or generic types

Upgrading from PostSharp 2.0

This new version is fully backward compatible with PostSharp 2.0 (except one breaking bug fix), and can be installed side-by-side with PostSharp 2.0. In order to upgrade, you should just update the references to PostSharp.dll (and possibly to PostSharp.targets, if PostSharp is installed in source control). A utility contained in PostSharp HQ helps you converting projects from 2.0 to 2.1.

The upgrade is free for everyone and your 2.0 license key will work with 2.1. However, you will be asked to enter your license key.

Even if you are happy with the features of 2.0, you have to upgrade to 2.1 because your projects are going to compile damn faster! Frankly. PostSharp has now the fastest MSIL engine on the market.

Announcing PostSharp 2.0 Update 6

By the way, we’ve also updated the PostSharp 2.0 release. It contains the following fixes compared to the previous update. Needless to say, these fixes are also included in the 2.1 release.

Aspect instance fields should not be marked as serializable
Aspects may conflict with themselves
Attempt to use two adornment layers when symbol file is updated
BaseMarkerManager.RefreshTextMarkers causes AccessViolationException
Collapsed region names should not be underlined by the VSX
CSharpLanguageAdapter.VisitPropertyAccessor causes CodeProperty.get_Parent to throw InvalidOperationException
Exception in MulticastAtributeTask when a parameter-level MulticastAttribute is applied to a property
Exception in MulticastAttributeTask with inheritance on generic methods
Exception when an aspect is applied to a generic protected method, or a protected method of a generic type, in a third assembly.
Exception when an aspect is applied to a virtual method of a sealed/value type
Exception with multicasting inheritance on generic methods.
ImportMember throws an exception when a member is a property and an accessor is missing.
In IntroduceMember, CopyCustomAttribute with merge does not work
Incompatibility of the PostSharp VSX with CodeRush - collapsed regions
Invalid code generation when several OnMethodBoundary aspects are applied
Invalid code generation with a MSIL-serialized aspect containing an array argument
Invalid handling of generic instances in reflection wrappers
Invalid MSIL generation when [IntroduceMember] is applied to a member with a generic type argument
InvalidCastException when IAspectProvider is used when MsilAspectSerializer, and a non-instrinsic is passed to the ObjectConstruction
InvalidComObjectException from SolutionWatcher constructor
ManagedDotNet40Platform.GetGetClrIdentityManagerProc throws COMException: The handle is invalid.
Many features MethodRefDeclaration fail when the method refers to an implicit method of multidimensional arrays
Method-level MulticastAttributes with multicast inheritance are not multicast to derived types accross assemblies
MSBuild step "PostSharp20CopyOutputToCodeAnalysis" can fail because of file locking
Multicast attributes are applied to anonymous methods, but should not
MulticastAttribute.TargetMemberAttributes is not respected for properties and events
NullReferenceException in QuickInfoTracker.OnMouseMove
ProjectWatcher.UpdateSymbolPath throws NullReferenceException
Some debugging sequence points are dropped
ToolInvocationHelper.InvokeTool process output listener causes ArgumentOutOfRangeException on
UpdateCheckUtility.BeginRetrieveMessages throws ThreadStartException
UpdateCheckUtility.BeginRetrieveMessages throws ThreadStartException
VsPackage.BeginInvoke throws COMException
Win32Exception in PostSharp.VisualStudio.HWndDispatcher.BeginInvoke
Windows Phone 7 does not support tail calls generated by PostSharp
WriteWeavingSymbolsTask.Execute throws UnauthorizedAccessException

What’s Next?

It has been precisely one year since I started working on PostSharp 2.1. Arguably, it took way too much time to get that release out of the door. And here’s why: most of our time was invested in building the company and spreading the work about AOP. Since July, I’ve started research and planning for the next major version of PostSharp and a new product code-named Resonance, which will be to .NET software what magnetic resonance is to human body (detailed and non-invasive imaging). We’ve hired two software developers and, while PostSharp 2.1 was maturing, we started real development on the new “thing”. You’re going to be amazed, I promise.

But today, we’ve become confident that PostSharp 2.1 is ready for production, and it’s a great time for you to upgrade.

Happy PostSharping!

-gael

Announcing: PostSharp Training

Britt King — Thu, 29 Sep 2011 05:26:00 PDT

We’re thrilled to finally announce the availability of PostSharp training, worldwide. We’ve assembled an experienced team of trainers and consultants to offer a comprehensive 2 day course that’s designed to bring you up to speed fast on aspect-oriented programming and PostSharp.

The course includes hands-on labs and discussion where you’ll learn how to:

create PostSharp aspects; and
successfully introduce PostSharp aspects into complex projects.

Upon completion, you’ll be able to apply what you’ve learned to your own applications, and produce cleaner, more efficient, higher quality code than ever before.

Meet our Training & Consulting Partners

Donald Belcham is a senior software developer, independent contractor, and agile development expert who is a strong supporter of fundamental OO patterns and practices. He is co-author of the book, Brownfield Application Development in .NET (Manning Press, 2008), and actively shares his expertise with other technical professionals at user groups, code camps and conferences held throughout the world. Past lectures have covered topics that encompass development practices, quality team leadership, and the intricacies of new and emerging technologies.

Golo Roden works as self-employed trainer and consultant for C#, JavaScript and web development – focusing on code quality and agile methods. In 2011 he launched the Agile Development Framework, a comprehensive approach which combines the successful elements of previous agile methods. He has written more than 100 articles for professional magazines, has given more than 50 talks at international conferences, and wrote a book on C# in 2008. Golo blogs regularly and writes a recurring column on C# specialties for dotnetpro magazine.

Endjin is a collaboration of like-minded people who are imbued with an infectious enthusiasm for solving business problems through the smart application of technology. Their endjin-eers are outstanding individuals who have come together from across the business, creative and technology community having demonstrated a mastery of their craft. Unconstrained by industry vertical, company size or budget; endjin is motivated by solving problems. Their goal is to energize your business whether it is through a 2 hour conversation or 2 years of team effort.

PostSharp Training Agenda

The standard public agenda is composed of the following modules (note: for private training other topics can be introduced after discussion with the trainer):

Introduction to AOP
Basic aspects
Applying aspects to code
Interception aspects
Aspect composition
Composite aspects
Deployment and build process integration
Targeting different platforms
Best practices

We’ve got more exciting training news coming in the weeks ahead and, if you sign-up now to request more information about PostSharp training, we’ll let you in on the exciting news (including an exclusive offer) before we announce it publicly.

Happy PostSharping!

-Britt

Announcing PostSharp 2.1 RC 2

Gael Fraiteur — Wed, 21 Sep 2011 02:21:37 PDT

I’m pleased to announce the second release candidate of PostSharp 2.1, available for download today on our web site and on NuGet. The first RC proved to be very stable, so this new version contains only relatively minor bug fixes. This RC also contains all bug fixes from the 2.0 branch.

Here’s the list of bugs that have been fixed in this release:

CopyCustomAttributes causes exception when several types are passed to the constructor
Fields are not visible by the debugger when a class has been moved to a binding class
ImageWriter sets the section virtual size to an invalid value, causing failure in Windows Phone
Invalid code generation when introducing a property or event of an open generic type
Invalid code generation when introducing a property with a private property setter
MainForm.CloseNotificationIcon throws InvalidOperationException after hibernation
MSBuild failure when building a project on a FAT system (hard links not supported)
PostSharp HQ throws exception when saving a license key for all users
Setup program displays maintenance dialog when in silent mode
Setup program prompts to uninstall previous version of the VS extension even in silent mode
The license registration wizard should not be displayed after a silent installation.
Exception in MulticastAtributeTask when a parameter-level MulticastAttribute is applied to a property
Unused AssemblyRefs are included in the final assembly
MulticastAttribute.TargetMemberAttributes is not respected for properties and events

PostSharp 2.1 is the fastest and most stable version of PostSharp and the upgrade is recommended for any one. To convert your projects, either use NuGet, either open PostSharp HQ and click on convert projects.

We’re now planning for PostSharp 3 and a new, truly disruptive, product that will change the landscape of instrumentation and diagnostic of in-production applications. We are hiring; drop us an email if you’re interested in joining the team.

Happy PostSharping!

-gael

PostSharp SDK is undocumented and unsupported

Gael Fraiteur — Tue, 20 Sep 2011 02:24:00 PDT

This is one of these unpopular but necessary decisions that every software publisher has to do now and then. It’s generally accepted that pulling off expensive but little-used features is a healthy decision because it frees resources that can be spent on more popular features. This is what we are doing with documentation and support of PostSharp SDK.

What is PostSharp SDK?

PostSharp is made of two principal components: PostSharp.dll and PostSharp.Sdk.dll.

PostSharp.dll is the high-level public API. It mostly contains interface definitions, abstract classes and custom attributes from which developers can derive their own aspects. This library is designed to be used by developers of business applications. It offers transformation primitives (such as: intercepting a method, wrapping a method, introducing an interface) that developers can add to their code. PostSharp.dll leverages real aspect-oriented programming, a disciplined extension of object-oriented programming. Just as a normal compiler, the high-level API enforces syntactic rules, and you will get a reasonable error message if you violate them.

PostSharp.Sdk.dll is the opposite of PostSharp.dll. Its public API allows you to modify .NET assemblies at a very low level. You can do everything. The API does not enforce any programming discipline or syntactic rules. You can create invalid assemblies without even getting a warning. It requires you to learn the MSIL specification and to understand most of the 565 pages of the ECMA-335 specification. PostSharp.Sdk.dll is made of several components. The most low-level ones (code model, image reader, image writer) are also found in Mono Cecil and Microsoft CCI, although PostSharp SDK has its own implementation. PostSharp SDK also includes several middle-level components such as the project loader, the aspect infrastructure (which could allow you to use PostSharp SDK to develop an aspect weaver that has different syntax than PostSharp.dll), the aspect weaver (the implementation of the PostSharp.dll), the custom attribute multitasking components, and much more.

PostSharp SDK is more complex than you think

Contrarily to PostSharp itself, PostSharp SDK has a very steep, but misleading, learning curve. You get quite quickly the illusion that you “got” it, but the devil is in details. The 80-20 rules does not apply to PostSharp SDK: what applies is 95-5: 95% of time is spent in addressing 5% of cases. Think of MSIL programming as hiking in high mountains without a map. You always have the illusion that the top is near, but whenever you climb on what appeared to be top, you discover another, higher top. If you want to have an idea of the effort you’ll need to reach the goal, you need a map; ECMA-335 and the PostSharp SDK class reference will give you a fair overview of the complexity of your task.

So why do we have PostSharp SDK? First, for our own needs. From our own point of view, PostSharp SDK is the most important component of PostSharp. Secondly, because this API is useful to a tiny minority of ISVs with very specific needs (for instance: high focus on speed). They can afford to maintain MSIL skills because the effort is leveraged to thousands of customers. Third, because PostSharp SDK can be used to overcome missing features of PostSharp.dll. But this is where things can go wrong.

PostSharp SDK is undocumented and unsupported

There has been some criticism that PostSharp SDK is undocumented. This is not accurate: the class reference is quite complete and contains more than what’s obvious from the method signature. Many actually claim that PostSharp SDK has the best documentation of all MSIL rewriting tools.

What is true is there is no conceptual documentation. Let me be clear: the lack of conceptual of documentation is a feature, not a defect. The SDK will not be better documented. As any company, we have to allocate limited resources to a potentially unlimited number of features. It does not economically make sense to spend time in documenting a very complex API that is used by a dozen of customers.

The same holds for support. We cannot provide support on a highly complex and incompletely documented API. We cannot guide you through baby steps. PostSharp SDK is not supported. You use it at your own risks.

Nostra Culpa

On the support forum, you could often read answers that sounded like “this is not possible to do with PostSharp.dll but can be done with PostSharp.Sdk.dll”, followed by a disclaimer that PostSharp SDK is hard and you should maybe not try. This had led some customers to ask for more information for these specific cases, which I published on the blog. Mistake! These blog posts have been interpreted as an advertisement of and an invitation to use PostSharp SDK. I apologize for that. I will not advertise PostSharp SDK again. It will remain unsupported and undocumented. The harmful blog posts have been withdrawn.

PostSharp SDK still available

That said, PostSharp SDK is still available for use in the Professional Edition. We are only making it clearer that this feature is not officially supported, and must be used at own risk. I believe that it’s not a good idea to code directly MSIL instructions unless you can leverage the effort to thousands of customers (as we do), but you’re free to try. It’s just that you’re on your own.

I’m aware this decision will be unpopular, but I’m convinced it’s a necessary one to continue provide good support to the community.

Happy PostSharping !

-gael

Announcing PostSharp 2.1 RC 1

Gael Fraiteur — Tue, 30 Aug 2011 07:41:02 PDT

I’m excited to announce the first release candidate of PostSharp 2.1, available for download from our website and from the NuGet official repository.

PostSharp 2.1 is a minor upgrade of PostSharp 2.0; the upgrade is free for everybody. The objective of this version is to fix several gray spots in the previous release.

This release candidate is ought to be of very high quality and free of known bugs, but needs to be tested by the community before it can be labeled stable. As required by the RC quality label, the online documentation has been updated to reflect the latest API.

PostSharp 2.1 has full backward binary compatibility with PostSharp 2.0.

What’s new in RC 1?

This release candidates contains the following additions to the previous CTP:

The design of architecture validation (PostSharp.Constraints) has been finalized.
Warnings can be disabled locally (for a specific element of code) using the IgnoreWarning custom attribute. See online documentation for details.
The PostSharp project property page in Visual Studio now allows you to specify which warnings should be globally ignored or escalated into errors.
Compatibility with Code Contracts 4.0
As an experimental feature, warnings and errors now come with file/line information. The feature must be enabled manually from Visual Studio options. We’re eager to hear feedback about this feature from customers with larger projects.
17 bug fixes

What’s new in PostSharp 2.1?

If you missed the previous announcements, here’s a list of new features in PostSharp 2.1 compared to version 2.0:

Improved build-time performance: up to 5x faster. Read more.
Architecture validation: build-time validation of design rules. Read more.
Extended reflection API: programmatically navigate code references. Read more and more.
NuGet packaging and improved no-setup deployment experience. Read more.
Support for obfuscators: we now support Dotfuscator. Read more.
Support for Silverlight 5.
Compatibility with Code Contracts 4.
Improved messaging API.
Tab page in Visual Studio project properties.
Streamlined licensing experience.
License server.
Streamlined “getting started” experience.

Upgrade your Projects

To upgrade your projects from PostSharp 2.0 to PostSharp 2.1 easily you can use the conversion utility included in the PostSharp HQ application. Just open the app and click on “convert”, then select the folder containing your projects. References to libraries and MSBuild imports will be automatically fixed.

PostSharp 2.1 Roadmap

A release candidate means that we are confident in the code quality and is that all mandatory quality work, including documentation, has been done. PostSharp 2.1 is now the default version on our download page. We’ll wait a couple of weeks to allow the community to give this version a try, then publish the RTM or another RC, according to the feedback.

Note that the license agreement allows for production use.

It’s now time to download PostSharp 2.1 and upgrade your projects!

Happy PostSharping!

-gael

New in PostSharp 2.1: Architectural Validation

Matthew Groves — Sat, 13 Aug 2011 12:57:00 PDT

The full source code for this blog post is available for download.

One of the most interesting features of PostSharp that sets it apart from other AOP tools is its ability to apply aspects at compile-time. As I've explored in previous blog posts, this gives you the ability to do compile time checking and initialization, insteaad of costly and error prone runtime validation. For instance, one could use CompileTimeValidate to enforce that a given aspect can only be used on MVC Controller methods.

    [Serializable]
    public class ConstrainedAspect : OnMethodBoundaryAspect
    {
        public override bool CompileTimeValidate(System.Reflection.MethodBase method)
        {
            if(!method.DeclaringType.IsSubclassOf(typeof(Controller)))
            {
                Message.Write(MessageLocation.Of(method),
				SeverityType.Error,
				"987",
				"Aspect can only be used on Controllers. " + 
				"You applied it on type {0}",
				method.DeclaringType.Name);
                return false;
            }
            return true;
        }

        public override void OnEntry(MethodExecutionArgs args)
        {
            var controller = (Controller) args.Instance;
            controller.ViewData["aspect"] =
			"Constrained Aspect was here at " + DateTime.Now;
        }
    }

This nifty feature has led some Postsharp users to create "aspects" that only contain compile time validation. An architect could put some code in here that helps to validate and enforce the architectural design: an "architectural unit test", if you will. With PostSharp 2.1, these "constraints" become a first-class feature.

There are two types of constraints available in PostSharp 2.1: scalar constraints and referential constraints. The separation is partially a semantic one, as both types of constraints are just ways of enforcing rules at compile time that the C# compiler itself doesn't give you. It's also a technical separation, as referential constraints are checked on all assemblies that reference the code element. (Note that you'll need to turn on architectural validation in the "PostSharp" tab of your project properties, and that this feature is available only in the professional version).

Scalar Constraints

A scalar constraint is a simple constraint that is meant to affect a single piece of code in isolation. This is the most like using a CompileTimeValidation method in an aspect, except without the aspect part. For instance, if you are a user of NHibernate, you know that your entity classes must have virtual properties. However, if you're like me, you might add a new property and forget to make it virtual. Then, you compile your project, run it, go through a test case, and get a runtime error. Wasted time! Here's a scalar constraint that you can apply to your entities to make sure you don't forget.

    [Serializable]
    [MulticastAttributeUsage(MulticastTargets.Class)]
    public class NHEntityAttribute : MulticastAttribute, IScalarConstraint
    {
        public void ValidateCode(object target)
        {
            var targetType = (Type)target;
            var properties = targetType.GetProperties(
			BindingFlags.Public | BindingFlags.Instance);
            var virtualProperties = properties.Where(p => !p.GetGetMethod().IsVirtual);
            foreach (var propertyInfo in virtualProperties)
            {
                Message.Write(MessageLocation.Of(targetType),
				SeverityType.Error,
				"998",
				"Property {0} in Entity class {1} is not virtual",
				propertyInfo.Name, targetType.FullName);
            }
        }

        public bool ValidateConstraint(object target)
        {
            return true;
        }
    }

Note that ValidateConstraint exists to validate the application of the constraint itself (a validation of a validation!). In my example above, I'm performing no validation at all and just returning true, but certainly you could check to make sure this validation is not applied to a static class, for instance. If ValidateConstraint method returns false, then the constraint is considered not valid, and will not be applied.

If you have all your entities in a single namespace, it's very easy to apply this constraint to all your entities (even ones that you haven't written yet) by multicasting that attribute. (For more info on multicasting, check out Dustin's excellent blog posts on multicasting: part 1 and part 2).

[assembly: NHEntity(AttributeTargetTypes = "YourNamespace.Models.Entities")]

When you forget the 'virtual' after you add a new property, you'll see something like this when you compile:

You could use constraints like this for similar situations, like WCF DataMembers in a DataContract or OperatingContracts in a ServiceContract. You can avoid a lot of frustration and wasted time.

Referential Constraints

Referential constraints are meant to enforce architectural design across assemblies, references, and relationships. This feature can be very useful, especially if you are writing an API. PostSharp actually ships with 3 out-of-the-box constraints for common scenarios: ComponentInternal, InternalImplements, and Internal.

ComponentInternal raises a compiler error if the code its applied to is used in a namespaces besides the one it resides in. For instance:

	// NamespaceA
	namespace PostsharpArchitecturalConstraints.API.NamespaceA
	{
		[ComponentInternal(Severity = SeverityType.Error)]
		internal class ApiA
		{
			public string GetFriendsName()
			{
				return "Mr. Friendly";
			}
		}
	}
	
	// NamespaceB
	using PostsharpArchitecturalConstraints.API.NamespaceA;
	namespace PostsharpArchitecturalConstraints.API.NamespaceB
	{
		public class ApiB
		{
			public string GetFriendsName()
			{
				var a = new ApiA();
				return a.GetFriendsName();
			}
		}
	}

If you want to specify some exceptions (a specific namespace that you want the internal class to be used in), you can do that in the ComponentInternal's constructor, but by default, it only allows code within its own namespace (and child namespaces) to call it.

InternalImplements is for use on interfaces, and limits implementations of the interface to its own assembly. This means the interface can stay public, for instance, but nothing outside the assembly can implement it.

	// in PostsharpArchitecturalConstraints.API assembly
	namespace PostsharpArchitecturalConstraints.API.Interface
	{
		[InternalImplement(Severity = SeverityType.Error)]
		public interface IPublicInterface
		{
			void DoOperation();
			string GetValue();
		}
	}

	// in PostsharpArchitecturalConstraints assembly
	using PostsharpArchitecturalConstraints.API.Interface;

	namespace PostsharpArchitecturalConstraints.Models.Services
	{
		public class MyPublicInterfaceImpl : IPublicInterface
		{
			private string _value;

			public void DoOperation()
			{
				_value = "operation complete";
			}

			public string GetValue()
			{
				return _value;
			}
		}
	}

Why would you want to do this? If you are designing an API, you may want the user to be able to reference an interface, and use your provided implementations of that interface, but you also may want to change your interface somewhere down the line. But, if you make changes to your interface, you could potentially break any implementations that the user has already made. By using InternalImplement, the user retains some flexibility in how they consume your API without the potential of their code breaking when they upgrade to your new version.

And finally, Internal. If you put Internal on a public item, it will remain public, but cannot be used by another assembly.

	// in one assembly
	[Internal]
	public class PublicAndInternal
	{
		public string GetValue()
		{
			return "this can only be called in its own assembly";
		}
	}

	// in another assembly
	public class TryingToUseInternal
	{
		public string Execute()
		{
			var publicInternal = new PublicAndInternal();
			return publicInternal.GetValue();
		}
	}

Of course, the door is wide open for you to write your own referential constraints. Here's one I wrote called Unsealable. It makes any classes inherited from the selected class unable to be sealed.

    [MulticastAttributeUsage(MulticastTargets.Class)]
    public class Unsealable : ReferentialConstraint
    {
        public override void ValidateCode(object target,
			System.Runtime.InteropServices._Assembly assembly)
        {
            var targetType = (Type) target;
            var sealedSubClasses = ReflectionSearch.GetDerivedTypes(targetType)
                                        .Where(t => t.DerivedType.IsSealed)
                                        .Select(t => t.DerivedType)
                                        .ToList();
            sealedSubClasses.ForEach(sealedSubClass => Message.Write(
				MessageLocation.Of(sealedSubClass), 
				SeverityType.Error,
				"997",
				"Error on {0}: subclasses of {1} cannot be sealed.",
				sealedSubClass.FullName, targetType.FullName));
        }
    }

This example also makes use of the handy ReflectionSearch utility that comes with PostSharp, which makes certain reflection tasks (like finding derived types in the above example) cleaner, easier, and Linq-ready. Here's an example of applying that constraint:

	[Unsealable]
	public class MyUnsealableClass
	{
		protected string _value;

		public MyUnsealableClass()
		{
			_value = "I'm unsealable!";
		}

		public string GetValue()
		{
			return _value;
		}
	}

	public sealed class TryingToSeal : MyUnsealableClass
	{
		public TryingToSeal()
		{
			_value = "I'm sealed!";
		}
	}

Constraints can be very valuable for larger teams, or for building an API that will be consumed by a larger audience (even an internal one). Don't go too crazy, though. Only build constraints that will help you, your team, and your API consumers save time and make less mistakes. By enforcing constraints on how code is to be used, you can protect yourself and your users from costly breaking changes down the road. It may be a politically sensitive issue, so good communication is still important, but it's very much like defensive programming, just at the architectual design level.

What’s New in PostSharp 2.1: Support for Obfuscation (Dotfuscator)

Gael Fraiteur — Mon, 25 Jul 2011 10:42:32 PDT

With prior versions of PostSharp, you had to be very careful to make your software compatible with any obfuscator. You could not obfuscate aspect classes, you could not store reflection objects, and you could not add use a reflection object in RuntimeInitialize with obfuscated generic methods. Indeed, all these features caused PostSharp to store the name of the metadata objects at build time, and to deserialize it at run time. But since the obfuscator renamed metadata objects after build time, the deserialization failed. Briefly said, previous versions of PostSharp were incompatible with all obfuscators.

PostSharp 2,1 provides a mechanism through which assemblies can be “repaired” after they have been obfuscated. Assemblies are still fully obfuscated, but PostSharp provides a utility to repair the name-object table. The build process is the following:

1. The compiler produces an assembly.

2. PostSharp post-processes the assembly and embeds an name table in the output assembly.

3. The obfuscator renames metadata objects, therefore breaks the PostSharp name table.

4. The post-obfuscation step (implemented by PostSharp) repairs the name table based on the obfuscation map produced by the obfuscator, and mapping the old name to the new name.

Since the post-obfuscation utility works with the obfuscation map, we need one implementation of this utility for every obfuscation map format, therefore for every obfuscation tool. PostSharp 2.1 includes support for Dotfuscator, the leading obfuscator .NET.

Calling the post-obfuscator

Let’s see how it works practically. You can download the example and try yourself.

To call the post-obfuscation step, you have to create an MSBuild project file and import the targets AddIns\PostSharp.AddIn.PostObfuscation.targets.

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" DefaultTargets="Build">

  <ItemGroup>
    <!-- Required: Path of dependencies of obfuscated assemblies. -->
    <ObfuscatedSearchPath Include="Dotfuscated" />
    <!-- Required: Path of dependencies of unobfuscated assemblies. -->
    <UnobfuscatedSearchPath Include="Unobfuscated"/>
    <!-- Required: Obfuscation map file produced by Dotfuscator. -->
    <MapFile Include="Dotfuscated\Map.xml"/>
    <!-- Required: Obfuscated files -->
    <ObfuscatedAssembly Include="Dotfuscated\*.dll"/>
    <ObfuscatedAssembly Include="Dotfuscated\*.exe"/>
    <!-- Optional -->
    <ContentFiles Include="Unobfuscated\*.config"/>
  </ItemGroup>

  <PropertyGroup>
    <!-- Required: output directory -->
    <OutputPath>$(MSBuildProjectDirectory)\Remapped</OutputPath>
    <!-- Required: selection of the remapping strategy -->
    <Obfuscator>Dotfuscator</Obfuscator>
  </PropertyGroup>


  <Target Name="Build" DependsOnTargets="PostObfuscationRemap">
    <!-- Optional: copy other files to the output directory-->
    <Copy SourceFiles="@(ContentFiles)" DestinationFolder="$(OutputPath)"/>
  </Target>

  <Target Name="Rebuild" DependsOnTargets="Clean;Build">
  </Target>
  
  <Import Project="..\..\Build\bin\AddIns\PostSharp.AddIn.PostObfuscation.targets" />
</Project>

As you can see, this file defines some locations (required items and properties), and calls the PostObfuscationRemap target defined in PostSharp.AddIn.PostObfuscation.targets.

Safe code references

The post-obfuscator ensures the following references to code are repaired after obfuscation:

References you are not aware of (used by PostSharp to provide the runtime features).
Reflection objects (for instance MethodInfo, Type) serialized inside objects using the default serializer (BinaryFormatter). This feature is implemented thanks to serialization surrogates for reflection objects.

There is no magic. Other strings referencing to a metadata element, and stored somewhere else than in a reflection object serialized by the default serializer, will not be fixed. If you wrote your custom aspect serializer and want to take advantage of metadata reference serialization, you have to play with IMetadataEmitter/IMetadataDispenser.

In other words, if you want to write obfuscation-safe aspects, the only serialized metadata references should be reflection objects in an aspect field (or somewhere under an aspect field).

Stripping of events and properties

Dotfuscator allows users to remove events and properties from code. The reason is simple: they are useless at runtime for the CLR. They are pure compiler syntactic sugar… or rather were, before XAML. So what if your aspect stores a PropertyInfo or EventInfo?

PostSharp will be smart enough to provide you with a PropertyInfo or EventInfo. The only visible difference is that the Name property will return null. Other properties and methods will work as usually. Under the hood, PostSharp will give you an object of type ObfuscatedPropertyInfo or ObfuscatedEventInfo instead of RuntimePropertyInfo or RuntimeEventInfo, but your code should not see the difference.

Support for other obfuscators

As a first step, we provide support for Dotfuscator. If other vendors are interested to support PostSharp, we’ll gladly provide them with the specification of the binary format. If you want to contribute a post-obfuscation filter, then be pleased that the Dotfuscator-specific code is only 56 lines long (parsing of their XML obfuscation map). The post-obfuscation add-in is not obfuscated so feel free to use a decompiler :).

Summary

That’s it for obfuscation. A small, unexciting feature, but people who need to obfuscate their applications don’t have any excuse not to use PostSharp!

Happy PostSharping!

New in PostSharp 2.1: Navigating Code Relationships

Gael Fraiteur — Fri, 22 Jul 2011 05:41:11 PDT

In my previous post, I introduced the new class ReflectionSearch and two of its methods: GetCustomAttributesOfType and GetCustomAttributesOnTarget. These methods give access to PostSharp’s internal repository of custom attributes.

Today, I would like to cover the second feature of ReflectionSearch: querying the relationships between elements of code. Three kinds of relationships are supported:

type inheritance (classes and interfaces),
usage in statements (a type, method, or field is used inside a method body),
member type,
any of the above, but as a type element (described below).

Navigating Type Inheritance

The system reflection API makes it easy to navigate from a child class to its parents, but the opposite is not true: if you want to retrieve all classes implementing a given interface in the assembly, you have to enumerate all types in this assembly, then enumerate all implemented interfaces, and do a recursion on the parent type. As was the case in the previous post with custom attributes, PostSharp indexes the type hierarchy for internal use. From PostSharp 2.1, ReflectionSearch exposes this feature to high-level aspects, and it comes with no performance cost.

The method ReflectionSearch.GetDerivedTypes does what it says, with one remark: by default, it returns only first-level derived types, i.e. it does not return derived types of derived types. If you want a deep search, you have to specify the option ReflectionSearchOptions.IncludeDerivedTypes.

Note that the method does not return an array of types, but of TypeInheritanceCodeReference. This object provides information about the base type. You may think the base type is always what you passed in the argument, but it isn’t always true. Consider the following code:

class GenericCollection<T> : ICollection<T> {}

class IntCollection : GenericCollection<int> {}

TypeInheritanceCodeReference[] derivedTypes = 
      ReflectionSearch.GetDerivedTypes( typeof(ICollection<>);

In this case, GetDerivedTypes would return two pairs: (GenericCollection<T>, ICollection<T>) and (IntCollection, ICollection<int>). In each case, the base type is a different instance of the generic type.

Navigating Usage

As a part of the post-compilation process, PostSharp scans all method bodies and builds a bi-directional map of using/used-by relationships, i.e. it determines which fields, methods or type are used in statements and expressions of a method body, and creates an index. This functionality is now available inside PostSharp.dll and is exposed on two methods:

ReflectionSearch.GetDeclarationsUsedByMethod returns the set of fields, methods and types used by a given method.
ReflectionSearch.GetMethodsUsingDeclaration returns all methods using a given field, method, or type.

As you can note, it is not possible to query references to properties and events. Indeed, properties and events are compiler “syntactic sugar” and are never referred to by instructions at MSIL level. If you want to query properties or events, you have to query each accessor separately (add, remove, get, set).

These methods return an array of MethodUsageCodeReference. This object contains both ends of the relationship, as well as a bit mask telling which instructions the declaration was used with – so you can distinguish between a get or a set operation on a field.

Navigating Member Types

The last thing you can do with ReflectionSearch is to get a list of all members of a given type. By member, I mean a field, a property, an event, a parameter, or a return-value parameter.

This feature is exposed on ReflectionsSearch.GetMembersOfType.

Note that PostSharp does not use this feature internally, so there is an additional performance cost in calling that method. The first time you invoke GetMembersOfType, the assembly will be scanned and indexed (using PostSharp’s internal APIes, not System.Reflection).

Type Elements

By default, all methods of ReflectionSearch match the exact type passed as an argument (or match derived types if ReflectionSearchOptions.IncludeDerivedTypes is specified). However, there are cases where you want a larger choice.

Consider the following code:

class Bar {}

class Foo : ICollection<Bar>
{
   Bar[] array;

   void ICollection<Bar> FooBar()
   {
     return new List<Bar>();
   }
}

var derivedTypes = ReflectionSearch.GetDerivedTypes( typeof(Bar), options );
var members = ReflectionSearch.GetMembersOfType( typeof(Bar), options );
var usages = ReflectionSearch.GetMethodsUsingDeclaration( typeof(Bar), options );

With the default value of options, the three methods return an empty set. Indeed, there is no type derived from Bar, no field or return value of type Bar, and no instruction using Bar. However, if you include the option ReflectionSearchOptions.IncludeTypeElement, you will get:

as derived type: Foo,
as members: the field array and the return value of FooBar, and
as usages: the method FooBar.

The IncludeTypeElement option asks PostSharp to index at a much deeper level. Pay attention: this comes at a performance cost. PostSharp does not use this feature internally, so the first time you use the option, it will have to scan all type signatures and build an index.

Summary

The new ReflectionSearch class allows you to make complex queries over System.Reflection. Most of the times, the features are already used internally by PostSharp, so they come at minimal performance cost.

The ReflectionSearch class is accessible at build time only. The primary use case is to write more powerful logic for IAspectProvider or MethodPointcut. The second use case is to validate your code. And this is for another blog post.

Happy PostSharping!

-gael

New in PostSharp 2.1: Reflecting Custom Attributes

Gael Fraiteur — Thu, 21 Jul 2011 07:41:03 PDT

One of the breaking innovations of PostSharp 1.0 in 2005 was the ability to execute aspect code at build time. Whereas other AOP frameworks developed complex declarative syntaxes to express “pointcuts”, PostSharp just allowed you to use System.Reflection to select the target of aspects. LINQ made it even easier to express complex code queries.

Yet, some queries were difficult to achieve just with System.Reflection. For instance, it is fairly difficult and inefficient to get all properties annotated with the [DataMember] custom attribute: you have to enumerate all types (and do a recursion on nested types), get all properties of these types, and check the presence of this custom attribute on all properties. Wow. If we were querying a relational database, we would probably create an index on the Type column of the CustomAttribute table. Well, the analogy is not so stupid. Metadata in a .NET assembly is in fact a relational database, and there is a CustomAttribute table. What is more, PostSharp already builds these indexes internally. So why not making them available to user code? This was the principal idea behind this new feature: reflection search.

Reflection Search is simply this: a set of methods making it easier and more efficient to query metadata of the assembly being processed by PostSharp. Therefore, this API is available only at build time. It is not intended to “improve” System.Reflection for run-time use. That said, if you need to do some complex reflection query at runtime, it’s better to do it at build time using PostSharp, serialize the result and store it as a managed resource.

The API is exposed in the class PostSharp.Reflection.ReflectionSearch. Note that the feature is available in the Professional Edition only.

Enumerating Custom Attributes

Custom attributes of a type

The first set of methods you will find on the ReflectionSearch class allow you to enumerate custom attributes. GetCustomAttributesOnType retrieve all custom attributes of a given type in the current assembly (remember that this works only at build time, so the notion of “current assembly” refers to the assembly being processed by PostSharp). The second overload takes an additional parameter ReflectionSearchOptions. If you specify the value IncludeDerivedTypes, you will get all custom attributes of the specified type or any type derived from it.

There is no example in the system class library to illustrate a hierarchy of custom attributes, so let's create our own:

// A hierarchy of custom attributes.

class FruitAttribute : Attribute {}

class AppleAttribute  : FruitAttribute {}

class OrangeAttribute : FruitAttribute {}

class VegetableAttribute : Attribute {}

class TomatoAttribute : VegetableAttribute {}

// Using the custom attributes

[Fruit]
class Team
{
   [Apple]
   Dude tom;

   [Orange]  
   Dude jerry;

   [Tomato]
   Dude donald;

}

// Enumerating the custom attributes (build-time)
class MyAspect : AssemblyLevelAspect, IAspectProvider
{
 
    public IEnumerable ProvideAspects(object target)
    {

      CustomAttributeInstances[] attributes = ReflectionSearch.GetCustomAttributesOfType( 
          typeof(FruitAttribute), ReflectionSearchOptions.IncludeDerivedTypes );

      // TODO: Do something with that.

    }

}

The method GetCustomAttributesType will return three instances of the custom attribute: (FruitAttribute, Team), (AppleAttribute ,Team.tom) and (OrangeAttribute, Team.jerry).

If you wonder why the method does not return a tomato: it is by decision of the U.S. Supreme Court, which, on May 10, 1893, declared that tomatoes are vegetables because – although they are classified as fruits in botany – they are usually served with dinner and not dessert. As far as I am concerned, I still don’t eat tomatoes for dessert, the only thing that changed is that we are now much more accustomed to bureaucracy (and today’s tomatoes have better resistance to pressure because the species were selected to accommodate mechanical picking, and long storage and transportation – so arguably we now eat more tomatoes than in the XIX^th century, but they are probably less tasty).

Anyway.

Note that the method returns a CustomAttributeInstance, which includes information about the custom attribute and the element of code to which it is applied.

Multicast attributes

Keep in mind that ReflectionSearch reflects the internal repository of custom attributes. This repository does not only include custom attributes that you add to your code manually. It also includes all “pseudo” custom attributes added by different components of PostSharp, starting with multicast attributes (remember that aspect class typically derive from MulticastAttribute).

When you use multicast custom attributes in your code, PostSharp executes the multicasting algorithm to populate the internal repository. The repository then contains the concrete instances of the custom attribute.

Let’s take an example:

[MulticastAttributeUsage( MulticastTargets.Method )]
class FooAttribute : MulticastAttribute {}

[Foo]
class MyClass
{
   void MyMethod() {}
}

In that case the repository contains an instance of FooAttribute on MyMethod but not on MyClass. The normal reflection API would give the opposite result (at least when it is run inside PostSharp or before PostSharp), because it is not aware of multicast semantics.

Since you can’t use normal reflection to retrieve multicast custom attributes, ReflectionSearch offers a second method: GetCustomAttributesOnTarget. As the name suggests, it returns the list of all custom attributes on a given element of code.

Summary

The high-level library PostSharp.dll now offers access to the internal repository of custom attributes. Since this repository, and all indexes, are used by PostSharp itself, using this new feature has minimal impact on build time. Now, you have a way to query custom attributes by type without killing performance. And you are finally able to query attributes that were created by PostSharp as the result of the multicasting algorithm.

But that’s not all ReflectionSearch has to offer. Next in line: browse relationships between elements of code. But this is for another day.

Happy PostSharping!

-gael

PostSharp Principles: Day 15 – Introducing Members and Interfaces, Part 2

Dustin Davis — Fri, 15 Jul 2011 08:34:00 PDT

Yesterday we introduced members into our target class. Today we’re going to go the other way and introduce members from our target class into our aspect for consumption by the process of importing.

Importing Members

There are cases when you will need to bring in a field or method from a target class so that you have access to it from within the aspect. What we’re doing is making assumptions about the target. It’s important to document what the aspect is assuming about the target code. Another approach instead of importing, is to cast the instance to a interface (or type) known to be implemented on the target.

To import, we use the ImportMember attribute. ImportMember allows us to import fields, properties, methods and events. As an example, let’s look at some sample code.

public interface IIdentifiable
{
    Guid ID { get; }
    void PrintID();

}

public class ExampleClass : IIdentifiable
{
    public Guid ID { get; private set; } //Satisfy the interface

    public ExampleClass()
    {
        this.ID = Guid.NewGuid();
    }

    [ImportExampleAspect]
    public void DoWork()
    {
        Console.WriteLine("Doing work");
    }

    public void PrintID()
    {
        Console.WriteLine(this.ID.ToString());
    }

}

[Serializable]
public class ImportExampleAspect : OnMethodBoundaryAspect, IInstanceScopedAspect
{
    [ImportMember("PrintID", IsRequired = true)]
    public Action PrintID;

    [ImportMember("ID")]
    public Property IDFromClass;

    public override void OnEntry(MethodExecutionArgs args)
    {
        Guid value = IDFromClass.Get();
        PrintID();
        Console.WriteLine("Value from IIdentifiable.ID is {0}", value.ToString());
    }

    public object CreateInstance(AdviceArgs adviceArgs)
    {
        return this.MemberwiseClone();
    }

    public void RuntimeInitializeInstance() {}

}

We have an example class that implements a simple interface and an aspect based on OnMethodBoundaryAspect. When you run this example code, the value of the ‘ID’ property will be written to the console.

178411e1-c79b-43fc-9aa0-ff309425abaa
Value from IIdentifiable.ID is 178411e1-c79b-43fc-9aa0-ff309425abaa
Doing work

Notice that our aspect implements the IInstanceScopedAspect interface. ImportMember cannot import static fields so we have to define our aspect as instance scoped. For more information on the life time and scope of aspects, refer to Day 9 and Day 10 of the PostSharp Principals series.

We expect the target to implement the interface which has a PrintID method defined. So we setup a public Action and we call it PrintID. We decorate our Action with the ImportMember attribute passing in the target’s member name which is ‘PrintID’.

Next we defined the IDFromClass public field of type Property<Guid>. This class has two properties: Get and Set. At runtime, the Get and Set properties will contain a delegate to the getter and setter of this property. In order to import an event, we need a public field of type Event<EventArgs>, which has two delegate properties: Add and Remove.

We do not have to use the same name as the target’s member name, so instead of ‘ID’ we are using ‘IDFromClass’.Inside of the OnEntry method we get the value of ID from our target class using the Get delegate provided by IDFromClass, make a call to the PrintID method and then write out the value to the console.

Note: ImportMember will work on members of any visibility, even private.

ImportMemberAttribute

There should be no surprise when I say that we can control the behavior of the import using the attribute’s parameters.

IsRequired

Specifies whether the member being imported is required or not. If true, a compiler error will occur if the member is not present in the target class. If false, the reference to the member will be null if it does not exist in the target.

Order

Order takes an enumeration from PostSharp.Aspects.Advices.ImportMemberOrder to determine when the importing will occur.

· AfterIntroductions (default) – Importing will occur only after the aspect has introduced its own members. This is useful if the imported member is virtual and we need to import the last override.BeforeIntroductions – Importing will occur before any members are introduced by the aspect. This gives you a chance to get a reference to the original member before any overriding occurs. This is similar to calling an overridden method by the “base” keyword.

· Default – The default is AfterIntroductions.

There can be any number of aspects on the same class that override the same method. Importing before the introductions allows you to call the next node in the chain of overwriting.

Better Example

Let’s have a look at a more in-depth example using both importing and introduction, the MakeDirtyOnChange aspect. When working with workspaces or MDI (multi-document interface) applications, many “documents” can be open at one time. There is a need to know when one or more of the “documents” have been modified so that you can inform the user visually and also to know which items need to be updated in the data store. Think about working with five C# files in Visual Studio. When a change is made to a file, you will see an asterisk next to the filename on the file’s tab. This is the indication that a change has been made and not yet saved.

Implementing the IsDirty pattern is similar to the INotifyPropertyChange, the code to wire up the change notification is redundant and tedious. Let’s check out our interface and test class before diving into our aspect

public interface IsDirty
{
    bool IsDirty { get; }
    event EventHandler WasMadeDirty;
    void ResetDirtyState();
    ReadOnlyCollection DirtyProperties { get; }
}

public class DirtyEventArgs : EventArgs
{
    public string DirtyProperty { get; private set; }

    public DirtyEventArgs(string dirtyProperty)
    {
        this.DirtyProperty = dirtyProperty;
    }
}

[MakeDirtyOnChange]
public class Document
{
    private Guid _docId = Guid.NewGuid();
    public Guid DocId { get { return _docId; } }

    public string Title { get; set; }
    public string Author { get; set; }
    public string Content { get; set; }
}

Our IDirty interface has a few requirements that we can and will use to determine if an item has changes. We specify a custom EventArgs class that allows us to provide details about the changes made to the item when invoking the WasMadeDirty event. Our Document class is a clean model that knows nothing about the IsDirty interface.

[Serializable]
[IntroduceInterface(typeof(IsDirty), OverrideAction = InterfaceOverrideAction.Ignore)]
public class MakeDirtyOnChange : InstanceLevelAspect, IsDirty
{
    [OnLocationSetValueAdvice, MulticastPointcut(Targets=MulticastTargets.Property)]
    public void OnValueChanged(LocationInterceptionArgs args)
    {
        MakeDirty(args.LocationName);
    }

    private bool _isDirty;
    private List _dirtyProperties;

    [ImportMember("SetDirty")]
    public Action MakeDirty;

    [IntroduceMember(IsVirtual=true, OverrideAction=MemberOverrideAction.Ignore)]
    public void SetDirty(string property)
    {
        _isDirty = true;
        if (WasMadeDirty != null)
        {
            WasMadeDirty.Invoke(this.Instance, new DirtyEventArgs(property));
        }
    }

    #region IsDirty Members

    [IntroduceMember(OverrideAction = MemberOverrideAction.Ignore)]
    public bool IsDirty { get { return _isDirty; } }

    [IntroduceMember(OverrideAction = MemberOverrideAction.Ignore)]
    public ReadOnlyCollection DirtyProperties { get { return _dirtyProperties.AsReadOnly(); } }

    [IntroduceMember(OverrideAction = MemberOverrideAction.Ignore)]
    public event EventHandler WasMadeDirty;

    [IntroduceMember(IsVirtual=true, OverrideAction=MemberOverrideAction.Ignore)]
    public void ResetDirtyState()
    {
        _isDirty = false;
        _dirtyProperties.Clear();
    }
 
    #endregion

    public override void RuntimeInitializeInstance()
    {
        _isDirty = false;
        _dirtyProperties = new List();
    }
}

We decorate our aspect with the IntroduceInterface attribute, specifying the IsDirty interface. Our aspect implements the IsDirty interface to satisfy the requirements and then we introduce those members to the target.

We setup a location interception using OnLocationSetValueAdvice attribute and specify the target is MulticastPointcut.Property ([MARKER, Advice link]). When a property is changed, we’re going to invoke the MakeDirty method which we tell PostSharp to import from the target’s “SetDirty” method, if it has one. We’re using the defaults for ImportMember which means the import will happen after our members are introduced. Since we’re introducing our own SetDirty method, MakeDirty will contain our SetDirty implementation if the target class did not already have its own implementation.

Since our aspect derives from InstanceLevelAspect we override the RuntimeInitializeInstance method and use it to initialize our private members to their default states.

We can use the following code to try out the aspect

class Program
{
    private static List _changedDocuments = new List();
    private static List _openDocuments = new List();

    static void Main(string[] args)
    {
        for (int i = 0; i < 5; i++)
        {
            Document doc = new Document();
            Post.Cast(doc).WasMadeDirty 
                += new EventHandler(doc_WasMadeDirty);

            _openDocuments.Add(doc);
        }

        _openDocuments[0].Author = "Dustin Davis";
        _openDocuments[0].Title = "PostSharp Principals - Day 1";

        _openDocuments[2].Author = "Dustin Davis";
        _openDocuments[2].Title = "PostSharp Principals - Day 3";

        Console.ReadKey();
    }

    static void doc_WasMadeDirty(object sender, DirtyEventArgs e)
    {
        Document doc = (Document)sender;

        if (_changedDocuments.Any(c => c.Equals(doc.DocId)))
        {
            return;
        }
            
        _changedDocuments.Add(doc.DocId);
        Console.WriteLine("Document {0} was modified.", doc.DocId);
    }
}

The code is pretty straight forward. We create five documents and then add them to our open documents collection. Finally we make changes to two documents. When we run the code, we see the following results

Document acbd247a-e742-499e-b27c-ee028e8e6789 was modified.
Document 9ded92cc-008f-48bc-b1b5-e1b0b967e42d was modified.

But wait, how are we handling the WasMadeDirty event? I’m glad you asked.

Post.Cast<>()

Post.Cast<>() allows us to cast an instance of a type to another type at design time. For example, our Document class doesn’t implement the IsDirty interface so we can’t access the IsDirty specific members unless we casting. We use the generic Cast<SourceType, TargetType>(SourceType Instance) method to give us back an instance of TargetType.

It’s basically nothing more than regular casting, but the difference is when you use Post.Cast<>() you receive compile-time errors if the cast cannot take place. The obvious benefit is that you know right away that the cast fails instead of at run time, potentially introducing bugs.

In the final result, the call to Post.Cast<>() is replaced with an actual cast.

Conclusion

Previous aspects we looked at have been pretty disconnected from the targets. Being able to introduce and import members gives us a connection and increased flexibility. Being able to automatically introduce interfaces and boiler plate code that is sometimes only consumed at run time frees us and keeps our code clean.

Dustin Davis Davis is an enterprise solutions developer and regularly speaks at user groups and code camps. He can be followed on Twitter @PrgrmrsUnlmtd or his blog Programmers-Unlimited.com

PostSharp Principles: Day 14 – Introducing Members and Interfaces, Part 1

Dustin Davis — Thu, 14 Jul 2011 08:28:00 PDT

Today we continue our descent into the depths of the PostSharp framework to expose even greater powers to utilize in our projects.

Introduction

No, not the “Hello, my name is Dustin!” kind of introduction, but the “injection” type. What does that mean? PostSharp gives us the power to implement an interface on a class…at build time. We can also add (introduce) members to that class such as fields/properties, events and methods too. These members are injected at build time and are available at run time.

Why would you want to do this? As in most cases when applying aspect-oriented programming, you would use this to implement required interfaces that are little more than boilerplate code. One of the most popular examples of interface introduction is the NotifyPropertyChanged aspect which automatically introduces the INotifyPropertyChanged interface and required members. Anyone who has worked with WPF and the MVVM pattern would love to not have to write all of that scaffolding code just to get change notification. Since that aspect uses features we have not yet covered, we will not cover it today. If you’re feeling adventurous, you can check it out here.

Member Introduction

Member introduction allows us to add properties, events and methods to a class. Let’s start off by creating an aspect to introduce a property and a method.

[Serializable]
public class IntroduceAspect : InstanceLevelAspect
{
    [IntroduceMember]
    public int ID { get; set; }

    [IntroduceMember]
    public void SomeMethod(int param1)
    {
        Console.WriteLine("Inside of introduced method");
    }

}

And now our target class

[IntroduceAspect]
public class TargetClass
{

}

You might be laughing at our test class, but don’t worry, our aspect will do the work for us. When we look at the compiled assembly with ILSpy, we see that instead of a blank class we have a few more members than we started with, including the members we wanted to introduce.

Amongst the aspect related code, we have our ID property and our SomeMethod method. Notice that the getter and setter of ID are delegated to our aspect and so does our method. This is important to keep in mind because when implementing members, they must be marked as public inside of the aspect (because our target class has to access them). However, if you happen to forget, PostSharp will remind you with a compiler error

But what happens if you don’t want the introduced members to be public in the target class? Have no fear, PostSharp thought of that too. Let’s have a look at the IntroduceMember attribute.

IntroduceMember attribute

By default, using IntroduceMember by itself will use public visibility and will cause compiler errors if a member with the same signature is already part of the class. We can control the behavior of how the member is implemented by changing the following parameters.

Visibility

By default, PostSharp will introduce the member to the target class with public visibility. We can specify one of the enumerations from PostSharp.Reflection.Visibility to control what visibility the member will have in the target class. Available values are

· Public (Default) – Is publically available.

· Family – Is available to the class and any derived classes. Same as protected.

· Assembly – Is publicly available within the assembly. Same as internal.

· FamilyOrAssembly – Is available to the class and any derived classes, but only within the assembly. Same as protected internal.

· FamilyAndAssembly – Protected types inside the assembly. There is no C# equivalent.

· Private – Only visible to the class.

OverrideAction

There is a chance that the target class already has a member with the same signature. By default, there will be a compiler error if this scenario is encountered. To change the behavior, we can provide one of the enumerations from PostSharp.Aspects.Advices.MemberOverrideAction.

· Default – Fails with a compiler error.

· Fail – Fails with a compiler error.

· Ignore – Continues on, without trying to introduce the member.

· OverrideOrFail – Tries to override the member with our own implementation. If the existing member is defined in a base class and is sealed or non-virtual, it will fail with a compiler error.

· OverrideOrIgnore – Tries to override the member with our own implementation. If the existing member is defined in a base class and is sealed or non-virtual, it will ignore the member introduction and continue on.

IsVirtual

If you would like to introduced member to be virtual (overridable in derived classes) then you can set IsVirtual to true. The member signature in the base class will be marked as virtual.

CopyCustomAttributesAttribute

Sometimes members need to be decorated with attributes. An example of this would be decorating members of a DataContract with DataMember. However, when introducing members from an aspect, any attributes applied to the member in the aspect will not be introduced along with the member in the target. We can use CopyCustomAttributes attribute in addition to the IntroduceMember attribute to introduce the attributes along with the member. Let’s look at an example.

[Serializable]
public class IntroduceAspect : TypeLevelAspect
{
    [IntroduceMember]
    [DataMember(IsRequired=true)]
    public int ID { get; set; }
}

[IntroduceAspect]
[DataContract]
public class TargetClass
{
    [DataMember]
    public string FirstName { get; set; }
}

Our aspect is introducing a member, ID, which is decorated with DataMember. Let’s look at the result in ILSpy

The DataMember attribute is not present on ID. Let’s update the aspect to use CopyCustomAttributes.

[Serializable]
public class IntroduceAspect : TypeLevelAspect
{
    [IntroduceMember, CopyCustomAttributes(typeof(DataMemberAttribute), 
            OverrideAction = CustomAttributeOverrideAction.MergeReplaceProperty)]
    [DataMember(IsRequired=true)]
    public int ID { get; set; }

}

In the constructor for CopyCustomAttributes we pass in the base type for the desired attribute and then we set the override action with a value from the CustomAttributeOverrideAction enumeration. When we look at the end result in ILSpy, we see that the attribute was introduced along with the member.

CustomAttributeOverrideAction

CustomAttributeOverrideAction is an enum that lets us tell PostSharp how to handle a situation when an attribute of the same type already exists on the target member.

· Default – Fails with a compile time error.

· Fail – Fails with a compile time error.

· Ignore – Ignores the attribute introduction and does not generate an error.

· Add – Adds the attribute as defined, even if it already exists on the target. This could cause duplicate attributes on the target.

· MergeAddProperty – Combines the existing attribute with the attribute being introduced. Any properties defined by the existing attribute will remain. No override will occur. Any properties defined by the introduced attribute will be added to the existing attribute.

· MergeReplaceProperty – Same as MergeAddProperty except that any properties defined by the existing attribute will overridden by the introduced attribute.

Interface Introduction

When introducing an interface via an aspect, the interface must be implemented on the aspect itself. The type will expose the interface at run time, but the aspect actually implements it. Let’s have a look at our interface:

public interface IFriendlyName
{
    string Name { get; set; }
    void PrintName();
}

And now our aspect:

[Serializable]
[IntroduceInterface(typeof(IFriendlyName))]
public class IntroduceAspect : InstanceLevelAspect, IFriendlyName
{
    #region IFriendlyName Members

    public string Name { get; set; }
        
    public void PrintName()
    {
        Console.WriteLine(this.Name);
    }

    #endregion
}

Our test class remains the same, empty

[IntroduceAspect]
public class TestClass
{

}

When we look at the compiled result we see our interface has been implemented

Notice that we didn’t use the IntroduceMember attribute on the interface members. Also notice that the resulting implementations of the interface members are private. To make the interface members public we have to apply the IntroduceMember attribute to the members

[Serializable]
[IntroduceInterface(typeof(IFriendlyName))]
public class IntroduceAspect : InstanceLevelAspect, IFriendlyName
{
    #region IFriendlyName Members

    [IntroduceMember]
    public string Name { get; set; }

    [IntroduceMember]
    public void PrintName()
    {
        Console.WriteLine(this.Name);
    }

    #endregion
}

And now the compiled result shows two implementations of our members

Looking at the PrintName method, the explicit interface implementation is private, but we’ve introduced a public version which the interface method calls.

IntroduceInterface attribute

To tell PostSharp that we want to introduce an interface, we decorate the aspect with the IntroduceInterface attribute. To tell PostSharp which interface to implement, we pass in a type using typeof(IFriendlyName). Just like the IntroduceMember attribute, there are parameters to control the behavior of the introduction.

· OverrideAction – Exactly the same as IntroduceMember. Determines what to do when the target already implements the interface. Default is to fail with a compiler error.

· IsProtected – If set to true, the interface is not directly implemented by the type. Instead, the type exposes the interface through the IProtectedInterface<T>. Since protected interfaces are considered obsolete, you should leave this as false (default).

· AncestorOverrideAction – Defines the behavior of the introduction when and ancestor of the interface is already applied to the target class. See example below. Available enumerations in the PostSharp.Aspects.Advices.InterfaceOverrideAction are Default (Fail), Fail and Ignore.

Extended Example

Let’s finish up with a bit more in-depth example using some of the behavior parameters.

public interface IIdentifiable
{
    Guid ID { get; set; }
}

public interface IFriendlyName : IIdentifiable
{
    string Name { get; set; }
    void PrintName();
}

[IntroduceAspect]
public class TargetClass : IIdentifiable
{
    #region IFriendlyNameBase Members

    public Guid ID { get; set; }   

    #endregion

    string Name { get; set; }

    public void PrintName()
    {
        throw new NotImplementedException();
    }
}

[Serializable]
[IntroduceInterface(typeof(IFriendlyName), 
                   AncestorOverrideAction=InterfaceOverrideAction.Ignore)]
public class IntroduceAspect : InstanceLevelAspect, IFriendlyName
{
    #region IFriendlyName Members
    [IntroduceMember(OverrideAction=MemberOverrideAction.Ignore)]
    public Guid ID { get; set; }   

    [IntroduceMember(OverrideAction=MemberOverrideAction.Ignore)]
    public string Name { get; set; }

    [IntroduceMember(OverrideAction=MemberOverrideAction.OverrideOrFail)]
    public void PrintName()
    {
        Console.WriteLine(this.Name);
    }

    #endregion
}

We define two interfaces. IFriendlyName implements IIdentifiable. Our test class implements IIdentifiable and also has a PrintName method which throws an exception. Our aspect specifies the introduction of IFriendlyName and also implements the required interface members. We specify that we should ignore any implementation of an ancestor (IIdentifiable) of the introduced interface (IFriendlyName). We also specify that we want to ignore the member introduction on the two properties if they exist in the target class. We mark PrintName with the OverrideOrFail because we want to force our own implementation of the PrintName method. The end result looks like this

First take a look at the PrintName method. Instead of the original method body, which threw an exception, we see that there is a call to our aspect which invokes our implementation of that method.

Next we see that both interfaces are implemented, but we only have get/set methods for the Name property, not the ID property. This is because PostSharp ignored the implementation of IIdentifiable since it was already implemented on the target class. If we remove InterfaceOverride.Ignore from the IntroduceInterface attribute, we would get a compiler error.

If we removed the implementation of IIdentifiable from our test class, we would see get/set methods for ID in the compiled results.

Conclusion

Today we covered some good ground on introducing members and interfaces along with some of the nuances that you have to be aware of. Tomorrow we’ll continue with importing members and accessing introduced members at compile time.

Dustin Davis Davis is an enterprise solutions developer and regularly speaks at user groups and code camps. He can be followed on Twitter @PrgrmrsUnlmtd or his blog Programmers-Unlimited.com

Announcing PostSharp 2.1 CTP 3

Gael Fraiteur — Thu, 14 Jul 2011 03:31:00 PDT

I'm pleased to announce that the third and final Community Technical Preview of PostSharp 2.1 is now available for download on our website and as a NuGet package.

The new CTP is principally a stabilization release, with a large number of bug fixes (including all hot fixes from the 2.0 branch) and some corrections in the new API design. This CTP is more stable than the latest builds on the 2.0 branch, but this has of course to be validated by the community.

What’s New in PostSharp 2.1 CTP 3

A streamlined experience for first-time users, including a redesigned PostSharp HQ application and new Learn PostSharp tool window in Visual Studio.
PostSharp does not enter the evaluation mode automatically. Instead, a dialog box will ask you to explicitly enter the evaluation mode. This adds a little friction for those evaluating PostSharp but should help to clarify any licensing questions.
Complete class reference documentation (the conceptual documentation is still not updated).
Support for Windows Phone 7.1 Beta.
Support for Silverlight and Windows Phone in the NuGet package.

What’s New in PostSharp 2.1 CTP 2

Architecture constraints.
Extended build-time reflection API.
Support for obfuscation.
Support for Silverlight 5.
License server.

What's New in PostSharp 2.1 CTP 1

Improvements in build-time performance.

What’s Next?

Now that the design is nearly finalized, we should finally blog about and document new features. The release candidate will be published as soon as the documentation is complete (the current release has been tested to release candidate-level quality).

Update Today

If your application is not going to production in the next few months, now is a great time to download PostSharp 2.1 and to upgrade your current application in a feature branch. Doing so will help us to validate the new version and move the final release date forward. Please report all issues on the support forum. Thanks!

Happy PostSharping!

-gael

PostSharp Principles: Day 13 – Aspect Providers, Part 2

Dustin Davis — Wed, 13 Jul 2011 08:24:00 PDT

When it comes to building complex aspects to solve a specific problem or implement a pattern, the base classes such as OnMethodBoundaryAspect and LocationInterceptionAspect aren’t always up-to the job. We covered the IAspectProvider yesterday, which allows us to dynamically tell PostSharp which aspects to apply to a target at compile time. Today we’re going to build complex aspects that encapsulate multiple transformations in a single aspect.

Advices and Pointcuts

Before we continue, we should cover some vocabulary. We’ve avoided the use of these terms until now to avoid any confusion.

· Advice – “An advice is anything that adds a behavior or a structural element to an element of code. For instance, introducing a method into a class, intercepting a property setter, or catching exceptions, are advices.”

· Pointcut – “A pointcut is a function returning a set of elements of code to which advices apply. For instance, a function returning the set of properties annotated with the custom attribute DataMember is a pointcut.”

When we override the OnEntry method when building an aspect based on OnMethodBoundaryAspect, we’re providing the advice to implement. By default the pointcut would be all methods in a class, if the class was decorated with our aspect based on the OnMethodBoundaryAspect base class.

PostSharp provides us with a set of attributes for declaring advice and pointcuts in any combination under a single aspect. Let’s have a look at an example to give a better picture

[Serializable]
public class ComplexAspect : TypeLevelAspect
{
    private int MethodCounter = 0; //Shared between all advices

    [OnMethodInvokeAdvice, MulticastPointcut(Targets =
                        MulticastTargets.Method, MemberName = "DoSomethingElse")]
    public void OnInvoke(MethodInterceptionArgs args)
    {
        Console.WriteLine("Before method {0}. MethodCounter = {1}", 
                                              args.Method.Name, this.MethodCounter);
        args.Proceed();
        Console.WriteLine("After method {0}. MethodCounter = {1}", 
                                              args.Method.Name, this.MethodCounter);
    }

    [OnMethodEntryAdvice, MulticastPointcut(Targets = MulticastTargets.Method)]
    public void OnEntry(MethodExecutionArgs args)
    {
        MethodCounter++;
        Console.WriteLine("Entering {0}. MethodCounter = {1}", 
                                               args.Method.Name, this.MethodCounter);
    }

    [OnMethodExitAdvice(Master = "OnEntry")]
    public void OnExit(MethodExecutionArgs args)
    {
        Console.WriteLine("Exiting {0}. MethodCounter = {1}", 
                                               args.Method.Name, this.MethodCounter);
    }

    [OnLocationSetValueAdvice, MulticastPointcut(Targets = MulticastTargets.Property)]
    public void OnPropertySet(LocationInterceptionArgs args)
    {
        MethodCounter++;
        Console.WriteLine("Setting property: {0} = {1}. MethodCounter = {2}", 
                                     args.LocationName, args.Value, this.MethodCounter);
    }
}

Our aspect derives from TypeLevelAspect, not one of the base classes we’ve been using. We have four methods in our aspect and each method is decorated with an advice attribute along with a pointcut attribute.

The OnEntry method is decorated with the OnMethodEntryAdvice attribute which has the same semantics of overriding the OnEntry method in an OnMethodBoundaryAspect. The MulticastPointcut attribute is used and passed the MulticastTargets.Method flag to let PostSharp know that we want to apply this advice to methods in general.

Because we’re using TypeLevelAspect instead of OnMethodBoundaryAspect, we are able to share state between advices. When using OnMethodBoundaryAspect, an instance of our aspect is created for each target. For example, Method1 would have its own copy of our aspect and Method2 would have its own copy. Using TypeLevelAspect to implement our advices changes that behavior; we have a single instance of our aspect that is used for each target which means that the advices get to share state. We’re going to demonstrate this using the MethodCounter field to increment on each method entry and display its value throughout the other advices.

Notice the OnExit advice isn’t specifying a pointcut, but instead is passing in a value to the Master parameter on the OnMethodExitAdvice attribute. We’re defining the master advice method, which means we’re grouping the advices on the same “layer”. OnExit will be a slave method and will inherit the pointcut selectors from OnEntry since only master advice methods can define pointcuts. We only do this for advices of the same category of transformations. For example, you wouldn’t define OnEntry as the master advice method for OnPropertySet because they perform different transformations. We’ll cover grouping on another day.

The other methods in our aspect are the same, just using different advices. The OnInvoke method however has a different pointcut setup. We add an additional parameter, MemberName, giving it a value of “DoSomethingElse” which tells PostSharp to only apply the advice to methods matching “DoSomethingElse”.

Let’s run our example code and look at the result

class Program
{
    static void Main(string[] args)
    {
        ExampleClass ec = new ExampleClass();
        ec.DoSomething();
        ec.DoSomethingElse();
        ec.FirstName = "John";
        ec.LastName = "Smith";

        Console.ReadKey();
    }
}

[ComplexAspect]
public class ExampleClass
{
    public string FirstName { get; set; }
    public string LastName { get; set; }

    public void DoSomething()
    {
        Console.WriteLine("Doing something");            
    }

    public void DoSomethingElse()
    {
        Console.WriteLine("Doing something else");
    }

}

Entering DoSomething. MethodCounter = 1
Doing something
Exiting DoSomething. MethodCounter = 1
Before method DoSomethingElse. MethodCounter = 1
Entering DoSomethingElse. MethodCounter = 2
Doing something else
Exiting DoSomethingElse. MethodCounter = 2
After method DoSomethingElse. MethodCounter = 2
Entering set_FirstName. MethodCounter = 3
Setting property: FirstName = John. MethodCounter = 4
Exiting set_FirstName. MethodCounter = 4
Entering set_LastName. MethodCounter = 5
Setting property: LastName = Smith. MethodCounter = 6
Exiting set_LastName. MethodCounter = 6

In a single aspect, we have implemented advice and pointcuts that we normally would have written three different aspects using the base classes. In addition, we were able to share state between those advices. Examine the output of the MethodCounter. It’s incrementing as we continue along with the execution. If we had three individual aspects the provided equivalent advices, the output would look more like

Entering DoSomething. MethodCounter = 1
Doing something
Exiting DoSomething. MethodCounter = 1
Before method DoSomethingElse. MethodCounter = 0
Entering DoSomethingElse. MethodCounter = 1
Doing something else
Exiting DoSomethingElse. MethodCounter = 1
After method DoSomethingElse. MethodCounter = 0
Entering set_FirstName. MethodCounter = 1
Setting property: FirstName = John. MethodCounter = 1
Exiting set_FirstName. MethodCounter = 1
Entering set_LastName. MethodCounter = 1
Setting property: LastName = Smith. MethodCounter = 1
Exiting set_LastName. MethodCounter = 1

Advices

There are a few advice attributes that you can use. Each advice attribute has a corresponding simple aspect base class and behaves in the same way.

OnMethodEntryAdvice OnMethodSuccessAdvice OnMethodExceptionAdvice OnMethodExitAdvice	These advices are the equivalent to the advices in the OnMethodBoundaryAspect base class
OnMethodInvokeAdvice	These advices are the equivalent to the advices in the MethodInterceptionAspect base class
OnLocationGetValueAdvice OnLocationSetValueAdvice	These advices are the equivalent to the advices in the LocationInterceptionAspect base class
OnEventAddHandlerAdvice OnEventRemoveHandlerAdvice OnEventInvokeHandlerAdvice	These advices are the equivalent to the advices in the EventInterceptionAspect base class
IntroduceMember	Introduce a method, property or event to the target class.
IntroduceInterface	Introduce a method to the target class.

When applying advice to a method, the method must be public and have the same signature as the corresponding base class advice signature. For example, in order to apply OnLocationGetValueAdvice on a method, the method must be public and have a single LocationInterceptionArgs parameter with no return value (void).

Pointcuts

A pointcut has to be defined in order to tell PostSharp where to apply the advice. You can think of pointcuts as expressions that return a set of elements of code. These elements of code must be compatible with the type of advice (for instance, do not try to add an OnLocationGetValue advice to a field). Remember that you can only add advices to code that belong to the target of the aspect. So if the aspect has been applied to a type, you can only add advices to members of this type, or to the type itself.

MulticastPointcut	A declarative pointcut that works similarly to MulticastAttribute.
MethodPointcut	An imperative pointcut: the pointcut is a method that returns an enumeration of elements of code. The method can be implemented in C#, for instance using Linq.
SelfPointcut	A pointcut that evaluates to the target of the aspect.

MulticastPointcut

MemberName

MemberName takes an expression (static name, wildcard or regular expression) to specify targets.

Targets

Targets can be set to a combination of MulticastTargets flags. For example, MulticastTargets.Method | MulticastTargets.Property to specify the targets will be methods and properties.

Attributes

Attributes is how we define the scope and visibility of the intended targets and can be set to a combination of MulticastAttributes flags. For example, we can target members that are private and static by using MulticastAttributes.Private | MulticastAttributes.Static.

MethodPointcut

MethodPointcut allows us to pass in the name of a method that PostSharp can use to get a list of targets. Let’s look at an example

[Serializable]
public class ExampleAspect : TypeLevelAspect
{
    public IEnumerable FindTargetMethods(Type target)
    {
        IEnumerable targets = target.GetMethods()
                         .Where(c => c.Name.Contains("Something"));
        return targets;
    }

    [OnMethodEntryAdvice, MethodPointcut("FindTargetMethods")]
    public void OnEntry(MethodExecutionArgs args)
    {
        Console.WriteLine("Entering method: " + args.Method.Name);
    }

}

Our aspect has only one advice that we want to implement, OnMethodEntryAdvice. We use the MethodPointcut attribute and pass it “FindTargetMethods” which is the name of the method we’ve setup to determine which methods will be targets. The method that is going to return the targets has to have a specific signature. PostSharp documentation defines this signature as

IEnumerable SelectCodeElements(AspectTargetType target)

AdviceTargetType will be replaced with either object or a reflection type representing the targets of the advice. For example, MethodInfo when the advice targets are methods and PropertyInfo when the targets are Properties.

AspectTargetType will be replaced with either object or a reflection type corresponding to the targets of the aspect. For example, Type for AssemblyLevelAspect, TypeLevelAspect, InstanceLevelAspect and MethodInfo for MethodLevelAspect.

If the signature is not valid for the type of aspect then PostSharp will produce a compiler error. When we apply the aspect to our example class and run the application, we see that PostSharp has applied the advice to both of the class methods.

public class Program
{
    static void Main(string[] args)
    {
        ExampleClass ec = new ExampleClass();
        ec.DoSomething();
        ec.DoSomething1();

        Console.ReadKey();
    }
}

[ExampleAspect]
public class ExampleClass
{
    public int ID { get; set; }
    public string First { get; set; }
    public string Last { get; set; }

    public void DoSomething()
    {
        this.First = "John";
        this.Last = "Smith";
    }

    public void DoSomething1()
    {
        Console.WriteLine("Did something");
    }
}

The output is

Entering method: DoSomething
Entering method: DoSomething1
Did something

SelfPointcut

There is a special attribute that you can use instead of MulticastPointcut, the SelfPointcut attribute. SelfPointcut tells PostSharp to select the exact aspect target. For example, if we have the following aspect

[Serializable]
public class ExampleAspect: MethodLevelAspect
{
    [OnMethodEntryAdvice, SelfPointcut]
    public void OnEntry(MethodExecutionArgs args)
    {
        Console.WriteLine("Entering " + args.Method.Name);
    }

}

When applied to a method directly, the SelfPointcut will use that exact method as the target. If applied to a class, all methods in the class will get the advice because all of the methods would be the intended target. If the aspect was applied at the assembly level with specific targets configured, then PostSharp will use those exact targets. SelfPointcut is a way to defer the selection of pointcuts to a higher mechanism.

Benefits over base classes

Base classes encapsulate a single transformation, which means if you want to apply multiple transformations, you would need to build just as many aspects. For example, if you wanted to marshal a method invocation to a different thread and log exceptions that occur in that method, you would need to build two independent aspects and apply both to the target.

Sharing state between advices in multiple independent aspects requires convoluted mechanics. Building complex aspects using advices and pointcuts provides the benefit of sharing state between advices.

Conclusion

By now you should have a clear understanding of how to build complex aspects using the tools provided by PostSharp. The term “complex” shouldn’t be a deterrent because over the last two days we’ve seen just how easy it is to build aspects.

Dustin Davis Davis is an enterprise solutions developer and regularly speaks at user groups and code camps. He can be followed on Twitter @PrgrmrsUnlmtd or his blog Programmers-Unlimited.com