PostSharp 4.1 User Manual Copyright SharpCrafters s.r.o. 2016. All rights reserved. 2 Table of Contents Introduction 7 Quick Examples 9 Why to Use PostSharp 13 Which Problems Does PostSharp Solves 13 Benefits of Pattern-Aware Compiler Extensions 14 Benefits of PostSharp vs Alternatives 15 How Does PostSharp Work 19 Key Technologies 19 How to Learn PostSharp 23 Architecture Role: Selecting and Creating Aspects 23 Deployment Role: Installing and Deploying PostSharp 25 Developer Role: Using Aspects 25 What's New in PostSharp 29 What's New in PostSharp 4.2 29 What's New in PostSharp 4.1 31 What's New in PostSharp 4.0 32 What's New in PostSharp 3.1 34 What's New in PostSharp 3.0 35 What's New in PostSharp 2.1 36 What's New in PostSharp 2.0 37 What's New in PostSharp 1.5 38 Deployment and Configuration 41 Deployment 43 Requirements and Compatibility 43 PostSharp Components 46 Installing PostSharp Tools for Visual Studio 47 Installing PostSharp Into a Project 47 Deploying License Keys 48 Using PostSharp on a Build Server 59 Upgrading from a Previous Version of PostSharp 62 Uninstalling PostSharp 64 Deploying PostSharp to End-User Devices 70 Configuration 71 Configuring Projects in Visual Studio 71 Configuring Projects Using MSBuild 73 Working with PostSharp Configuration Files 77 Accessing Configuration from Source Code 84 Working with Errors, Warnings, and Messages 85 Standard Patterns 89 INotifyPropertyChanged 91 Walkthrough: Automatically Implementing INotifyPropertyChanged 91 Walkthrough: Working with Properties that Depend on Other Objects 95 Implementing INotifyPropertyChanging 97 Handling Corner Cases 98 Understanding the NotifyPropertyChanged Aspect 100 Parent/Child Relationships 105 Walkthrough: Annotating an Object Model for Parent-Child Relationships 106 Walkthrough: Enumerating Child Objects 109 Walkthrough: Automatically Disposing Children Objects 110 Working With Collections 113 Using Immutable Collections 117 Undo/Redo 119 3 Table of Contents Making Your Model Recordable 119 Adding Undo/Redo to the User Interface 121 Customizing Undo/Redo Operation Names 123 Assigning Recorders Manually 127 Adding Callbacks on Undo and Redo 129 Understanding the Recordable Aspect 129 Contracts 133 Walkthrough: Adding Contracts to Code 133 Creating Custom Contracts 137 Localizing Contract Errors 139 Logging 143 Walkthrough: Adding Detailed Tracing to a Code Base 143 Walkthrough: Customizing Logging 147 Walkthrough: Tracing Parameter Values Upon Exception 153 Walkthrough: Changing the Logging Back-End 158 Adding Aspects to Code 159 Adding Aspects Declaratively Using Attributes 160 Adding Aspects Using XML 176 Adding Aspects Programmatically using IAspectProvider 177 Miscellaneous 179 Executing Code Just After the Assembly is Loaded 179 Threading Patterns 181 Writing Thread-Safe Code with Threading Models 183 Freezable Threading Model 184 Immutable Threading Model 188 Actor Threading Model 192 Reader/Writer Synchronized Threading Model 197 Synchronized Threading Model 202 Thread-Unsafe Threading Model 206 Thread Affine Threading Model 209 Making a Whole Project or Solution Thread Safe 212 Opting In and Out From Thread Safety 214 Compatibility of Threading Models 216 Enabling and Disabling Runtime Verification 217 Run-Time Performance of Threading Model 220 Dispatching a Method to Background 223 Dispatching a Method to the UI Thread 225 Detecting Deadlocks at Runtime 227 Custom Patterns 235 Developing Custom Aspects 237 Developing Simple Aspects 237 Understanding Aspect Lifetime and Scope 279 Initializing Aspects 281 Validating Aspect Usage 282 Developing Composite Aspects 285 Coping with Several Aspects on the Same Target 296 Understanding Interception Aspects 300 Understanding Aspect Serialization 301 Customizing Aspect Appearance in Visual Studio 302 Advanced 305 Examples 308 Testing and Debugging Aspects 321 Writing Simple Tests 321 Testing that an Aspect has been Applied 323 Consuming Dependencies from the Aspect 324 Testing Build-Time Logic 337 Attaching a Debugger at Build Time 338 Validating Architecture 341 Restricting Interface Implementation 341 4 Controlling Component Visibility Beyond Private and Internal 345 Developing Custom Architectural Constraints 353 5 PART 1 Introduction CHAPTER 1 Quick Examples This section shows a few examples to demonstrate what PostSharp is about: • Standard patterns on page 9 • Thread safety patterns on page 10 • Implementation of custom patterns on page 11 • Validation of custom patterns on page 11 Standard patterns PostSharp provides implementations of some of the patterns that are the most commonly found in .NET code bases: • INotifyPropertyChanged: see INotifyPropertyChanged on page 91. • Parent/child relationships: see Parent/Child Relationships on page 105. • Undo/redo: see Undo/Redo on page 119. • Code contracts: see Contracts on page 133. • Logging: see Walkthrough: Adding Detailed Tracing to a Code Base on page 143. Example The following code snippet illustrates an object model where INotifyPropertyChanged, undo/redo, code contracts, aggregation and code contracts are all implemented using PostSharp ready-made attributes. [NotifyPropertyChanged] public class CustomerViewModel { [Required] public Customer Customer { get; set; } public string FullName { get { return this.Customer.FirstName + " " + this.Customer.LastName; } } } [NotifyPropertyChanged] [Recordable] public class Customer { public string FirstName { get; set; } public string LastName { get; set; } [Child] public AdvisableCollection<Address> Addresses { get; set; } [Url] public string HomePage { get; set; } [Log] public void Save(DbConnection connection) { // ... } } 9 Quick Examples [NotifyPropertyChanged] [Recordable] public class Address { [Parent] public Customer Parent { get; private set; } public string Line1 { get; set; } } Thread safety patterns Multi-threading is a great demonstration of the limitations of conventional object-oriented programming. Thread synchronization is traditionally addressed at an absurdly low level of abstraction, resulting in excessive complexity and defects. Yet, several design patterns exist to bring down the complexity of multi-threading. New programming languages have been designed around these patterns: for instance Erlang over the Actor pattern and functional programming over the Immutable pattern. PostSharp gives you the benefits of threading design patterns without leaving C# or VB. PostSharp supports the following threading models and features: • Immutable: see Immutable Threading Model on page 188. • Freezable: see Freezable Threading Model on page 184. • Actor: see Actor Threading Model on page 192. • Reader/Writer Synchronized: see Reader/Writer Synchronized Threading Model on page 197. • Synchronized: see Synchronized Threading Model on page 202. • Thread Unsafe: see Thread-Unsafe Threading Model on page 206. • Thread Affine: see Thread Affine Threading Model on page 209. • Thread Dispatching: see Dispatching a Method to Background on page 223 and Dispatching a Method to the UI Thread on page 225. • Deadlock Detection: see Detecting Deadlocks at Runtime on page 227. Example The following code snippet shows how a data transfer object can be made freezable, recursively but easily: [Freezable] public class Customer { public string Name { get; set; } [Child] public AdvisableCollection<Address> Addresses { get; set; } } [Freezable] public class Address { [Parent] public Customer Parent { get; private set; } public string Line1 { get; set; } } public class Program { public static void Main() 10 { Customer customer = ReadCustomer( "http://customers.org/11234" ); // Prevent changes. ((IFreezable)customer).Freeze(); // The following line will cause an ObjectReadOnlyException. customer.Addresses[0].Line1 = "Here"; } } Implementation of custom patterns The attributes that implement the standard and thread safety patterns are called aspects. This terms comes from the paradigm of aspect-oriented programming (AOP). An aspect is a class that encapsulates behaviors that are injected into another class, method, field, property or event. The process of injecting an aspect into another piece of code is called weaving. PostSharp weaves aspects at build time; it is also named a build-time aspect weaver. PostSharp Aspect Framework is a pragmatic implementation of AOP concepts. All ready-made implementations of patterns are built using PostSharp Aspect Framework. You can use the same technology to automate the implemen- tation of your own patterns. To learn more about developing your own aspects, see Developing Custom Aspects on page 237. Example The following code snippet shows a simple [PrintException] aspect that writes an exception message to the console before rethrowing it: [Serializable] class PrintExceptionAttribute : OnExceptionAspect { public override void OnException(MethodExecutionArgs args) { Console.WriteLine(args.Exception.Message); } } In the next snippet, the [PrintException] aspect is applied to a method: class Customer { public string FirstName { get; set; } public string LastName { get; set; } [PrintException] public void Store(string path) { File.WriteAllText( path, string.Format( "{0} {1}", this.FirstName, this.LastName ) ); } } Validation of custom patterns Not all patterns can be fully implemented by the compiler. Many patterns involve a lot of hand-written code. However, they are still patterns because we want to follow the same conventions and approach when solving the same problem. In this case, we have to validate the code against implementation guidelines of the pattern.