PostSharp 3.0 Reference Documentation Copyright SharpCrafters s.r.o. 2013. All rights reserved. Generated on 2013-10-09T22:03:38+02:00 PostSharp 3.0 Documentation 2 PostSharp 3.0 Documentation Table of Contents What's New in PostSharp? 7 Deploying and Configuring PostSharp 13 Requirements 13 Installing PostSharp 14 Deploying License Keys 17 Configuring PostSharp 25 Using PostSharp on a Build Server 32 Restoring packages at build time 33 Upgrading from PostSharp 2 34 Installing PostSharp Unattended 36 Incompatibilities with Other Products 38 Working with Ready-Made Aspects 41 Working with the Diagnostics Pattern Library 41 Working with the Threading Pattern Library 55 Working with the Model Pattern Library 90 Adding Aspects to Code 113 Adding Aspects Declaratively Using Attributes 114 Adding Aspects Using XML 136 Adding Aspects Programmatically using IAspectProvider 137 Developing Custom Aspects 141 Developing Simple Aspects 141 Understanding Aspect Lifetime and Scope 178 Validating Aspect Usage 180 Initializing Aspects 184 Developing Composite Aspects 185 Coping with Several Aspects on the Same Target 201 Targeting Windows Phone, Windows Store or Silverlight 205 Understanding Interception Aspects 206 Understanding Aspect Serialization 208 Testing and Debugging Aspects 210 Advanced 232 Examples 235 Enforcing Design Rules 253 Restricting Interface Implementation 253 Controlling Component Visibility Beyond Private and Internal 258 Developing Custom Architectural Constraints 270 Working with Errors, Warnings, and Messages 281 Ignoring and Escalating Warnings 281 3 PostSharp 3.0 Documentation Emitting Errors, Warnings, and Messages 282 Combining with Other Technologies 285 ASP.NET 285 ILMerge 285 Obfuscation Tools 286 Microsoft Code Analysis (FxCop) 286 4 PostSharp 3.0 Documentation Conceptual Documentation PostSharp is a tool that allows development teams to achieve more with less code in Microsoft .NET: 1. Software developers will write clean, stable, efficient, and concise code. Fewer lines of code mean less time and fewer defects. 2. Software architects will be able to deliver partially or fully executable patterns, not just coding guidelines. After having carefully identified and selected design patterns, architects can code, in C# or Visual Basic, how the pattern should be implemented. Depending on the complexity of the pattern, PostSharp will automatically implement the pattern and/or will automatically validate that its manual implementation respects predefined validity rules. This topic contains the following sections. • About Design Pattern Automation at page 5 • PostSharp components at page 6 • How does PostSharp work? at page 6 About Design Pattern Automation PostSharp can be categorized as a Design Pattern Automation tool. Design Pattern Automation is the use of tools to optimize productivity of development teams implementing software based on patterns. Software patterns are general reusable solutions to a commonly occurring problem. Software design patterns are patterns in the context of software design. Typically, the architecture team would identify and select design patterns in an early phase of a project. Architects would then create designs that implement the design patterns. These designs typically include class diagrams, and instructions specifying how developers should implement the design. Design specifications are usually expressed in natural language. Design Pattern Automation refers to the ability to express designs in a formal language and use tools to help implementing the design. Tools can help developers and architects in implementing designs derived from patterns in two ways: • Tools can automatically implement some of the artefacts and behaviors required by the design, which then don't appear in source code. Design Pattern Automation therefore raises the level of abstraction of the source code, and makes the design intent more apparent in source code. 5 PostSharp 3.0 Documentation • Tools can validate hand-written code against design rules, from simple naming conventions to complex rules involving analysis of source code. Without tools, this activity would have only relied on code review. Design Pattern Automation can extend to patterns that are not strictly considered design patterns: • Design Pattern Automation extends to application-specific patterns (also named custom patterns), which are specific to the language, framework, and problem domain of an application. Althought these patterns are not general to the whole software engineering industry, their implementation can also be automatically generated and/or validated. • Design Pattern Automation extends to implementation patterns, which are mere repetitions of code. Logging and exception handling belong to that category. PostSharp components PostSharp is composed of the following frameworks and libraries: • PostSharp Pattern Libraries provide ready-made, commoditized implementations of some of the most common patterns in .NET. For more information, see section Working with Ready- Made Aspects at page 41. • PostSharp Aspect Framework allows you to automate the implementation of other code patterns and address code repetitions that are specific to your own applications, or simply that are not available off-the-shelf in a pattern library. PostSharp Aspect Framework is built on the principle of Aspect-Oriented Programming (AOP), a well-established programming paradigm, orthogonal to (and non-competing with) object-oriented programming or functional programming, that allows to modularize the implementation of some features that would otherwise cross-cut a large number of classes and methods. PostSharp contains the most advanced AOP framework for Microsoft .NET. For more information, see sections Developing Custom Aspects at page 141 and Adding Aspects to Code at page 113. • PostSharp Architecture Framework is a static analysis tool that allows you to automate the validation of design pattern implementations, to enforce design intend, or simply to verify coding guidelines. The framework allows you to create constraint classes that encapsulate the validation logic and that can be applied to code artefacts. The framework provides tools to analyze the relationships between code artefacts and have access to the AST of method bodies. For more information, see section Enforcing Design Rules at page 253. How does PostSharp work? PostSharp inserts itself in the build process and enhances or validates the output of the C# or VB compiler. Although this might sound magic or dangerous, PostSharp's MSIL technology is stable and mature, and has been used by tens of thousands of projects since 2004. Other .NET products relying on MSIL transformation or analysis include Microsoft Code Contracts, Microsoft Code Analysis, and Microsoft Code Coverage. 6 PostSharp 3.0 Documentation CHAPTER 1 What's New in PostSharp? PostSharp has been around since the early days of .NET 2.0 in 2004. Since the first version, many features have been added to make PostSharp the most popular and by far the most powerful tool for aspect-oriented programming and design pattern automation in .NET. What's New in PostSharp 3.0? The focus in PostSharp 3.0 was to deliver more value to customers with less initial learning. Instead of having to learn the product before being able to build aspects, customers can now choose from a set of ready-made implementations of some of the most popular design pattern, and apply them to their application from the Visual Studio code editor, using smart tags and wizards. We also improved support for Windows Phone, Silverlight, Windows Store and Portable Class Library. Model Pattern Library The NotifyPropertyChangedAttribute aspect is a ready-made implementation of the NotifyProperty- Changed design pattern. The PostSharp.Patterns.Contracts namespace provides code contracts that can validate, at runtime, the value of a parameter, a property, or a field. Diagnostics Pattern Library The LogAttribute and LogExceptionAttribute aspects provide a ready-made and high-performance implementation of a tracing aspect. They are compatible with the most popular logging framework, including log4net, nlog, and Enterprise Library. Threading Pattern Library PostSharp Threading Pattern Library invites you to raise the level of abstraction in which multithreading is being addressed. It provides three threading models: actors (Actor), reader-writer synchronized (ReaderWriterSynchronizedAttribute) and thread unsafe (ThreadUnsafeAttribute). Additionally, BackgroundAttribute and DispatchedAttribute allow you to easily dispatch a thread back and forth between a background and the UI thread. Smart Tags and Wizards in Visual Studio Smart tags allow for better discoverability of ready-made aspects and pattern implementations. When the aspect requires configuration, a wizard user interface collects the parameters and then generates the proper code. Better platform support through Portable Class Libraries Windows Phone, Windows Store and Silverlight are now first-class citizens. All features that are available for the .NET Framework now also work with these platforms. All platforms are supported 7 PostSharp 3.0 Documentation transparently through the portable class library. To provide this feature, we had to develop the PortableFormatter, a portable serializer similar in function to the BinaryFormatter. All you have to do is to replace [Serializable] with [PSerializable]. Unified deployment through NuGet and Visual Studio Gallery Installation of PostSharp is now unified and built on top