PostSharp 6.4 User Manual Copyright SharpCrafters s.r.o. 2020. All rights reserved. 2 Table of Contents Introduction 7 Quick Examples 9 Why Use PostSharp 13 Which Problems Does PostSharp Solve 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 27 What's New in PostSharp 6.4 27 What's New in PostSharp 6.3 29 What's New in PostSharp 6.2 30 What's New in PostSharp 6.1 31 What's New in PostSharp 6.0 33 What's New in PostSharp 5.0 35 What's New in PostSharp 4.3 38 What's New in PostSharp 4.2 39 What's New in PostSharp 4.1 42 What's New in PostSharp 4.0 42 What's New in PostSharp 3.1 44 What's New in PostSharp 3.0 45 What's New in PostSharp 2.1 46 What's New in PostSharp 2.0 47 What's New in PostSharp 1.5 49 Deployment and Configuration 51 Deployment 53 Requirements and Compatibility 53 PostSharp Components 57 Installing PostSharp Tools for Visual Studio 59 Installing PostSharp Tools for Visual Studio Silently 59 Installing PostSharp Into a Project 60 Installing PostSharp without NuGet 61 Using PostSharp on a Build Server 62 Upgrading from a Previous Version of PostSharp 65 Uninstalling PostSharp 67 Deploying PostSharp to End-User Devices 73 Licensing 75 Deploying License Keys 75 License Audit 79 Limitations of PostSharp Essentials 79 Sharing Source Code With Unlicensed Teams 80 Installing and Servicing PostSharp License Server 81 Using PostSharp License Server 85 Configuration 91 Configuring Projects in Visual Studio 91 Configuring Projects Using MSBuild 93 Working with PostSharp Configuration Files 97 Accessing Configuration from Source Code 103 Working with Errors, Warnings, and Messages 104 3 Table of Contents Resolution of assembly binding redirections 106 Adding Aspects to Code 109 Adding Aspects Declaratively Using Attributes 111 Adding Aspects to a Single Declaration 112 Adding Aspects to Multiple Declarations 112 Adding Aspects to Derived Classes and Methods 117 Overriding and Removing Aspect Instances 123 Reflecting Aspect Instances at Runtime 126 Adding Aspects Using XML 129 Adding Aspects Programmatically using IAspectProvider 131 Logging 133 Adding Detailed Logging to your Solution 135 Configuring Specific Logging Frameworks 139 Logging to the System Console 140 Logging to log4net 140 Logging to NLog 141 Logging to Serilog 142 Logging to ETW 144 Logging to Common.Logging 144 Logging to Loupe 145 Customizing the Appearance of Log Records 147 Adding Custom Log Records Manually 151 Writing Custom Messages 151 Working with Custom Activities 155 Adding Properties to Messages and Activities 158 Enabling and Disabling Logging At Run Time 161 Implementing Logging for a Distributed System 163 Choosing Which Requests to Log 169 Implementing a Custom Formatter 171 Adding Audit to your Solution 173 Implementing an Adapter to a Custom Logging Framework 177 Handling Faults in the Logging Component 183 Licensing of PostSharp Logging 185 Upgrading Logging from an Earlier Version 187 Contracts 189 Adding Contracts to Code 191 Creating Custom Contracts 195 Localizing Contract Error Messages 197 Customizing Contract Exceptions 201 INotifyPropertyChanged 203 Implementing INotifyPropertyChanged 205 Working with Properties that Depend on Other Objects 207 Implementing INotifyPropertyChanging 209 Handling Corner Cases 211 Integrating with UI Frameworks 215 Caliburn.Micro 215 MVVM Light 217 Understanding the NotifyPropertyChanged Aspect 219 Suppressing False Positives 223 Weak Event 225 XAML 227 Command 229 Dependency Property 233 4 Attached Property 237 Parent/Child, Visitor and Disposable 239 Annotating an Object Model for Parent/Child Relationships (Aggregatable) 241 Rule-Based Annotation 243 Enumerating Child Objects (Visitor) 245 Automatically Disposing Children Objects (Disposable) 247 Working With Child Collections 249 Undo/Redo 255 Making Your Model Recordable 257 Adding Undo/Redo to the User Interface 259 Customizing Undo/Redo Operation Names 261 Assigning Recorders Manually 265 Adding Callbacks on Undo and Redo 267 Understanding the Recordable Aspect 269 Caching 273 Caching Method Return Values 275 Removing Items From the Cache 279 Working with Cache Dependencies 283 Customizing Cache Keys 289 Caching Back-Ends 293 Using In-Memory Cache 293 Using Redis Cache 293 Synchronizing Local In-Memory Caches for Multiple Servers 297 Caching Special Types with Value Adapters 299 Preventing Concurrent Execution of Cached Methods 303 Troubleshooting Caching 305 Multithreading 307 Writing Thread-Safe Code with Threading Models 309 Immutable Threading Model 310 Freezable Threading Model 314 Thread Affine Threading Model 316 Synchronized Threading Model 317 Reader/Writer Synchronized Threading Model 319 Actor Threading Model 325 Thread-Unsafe Threading Model 328 Making a Whole Project or Solution Thread Safe 329 Opting In and Out From Thread Safety 331 Compatibility of Threading Models 332 Enabling and Disabling Runtime Verification 333 Run-Time Performance of Threading Model 336 Dispatching a Method to Background 339 Dispatching a Method to the UI Thread 341 Detecting Deadlocks at Runtime 343 Developing Custom Aspects 349 Developing Simple Aspects 351 Injecting Behaviors Before and After Method Execution 351 Handling Exceptions 359 Intercepting Methods 364 Intercepting Properties and Fields 368 Intercepting Events 374 Introducing Custom Attributes 377 Introducing Managed Resources 381 Semantic Advising of Iterator and Async Methods 382 Understanding Aspect Lifetime and Scope 389 5 Table of Contents Initializing Aspects 391 Coping with Custom Object Serializers 391 Validating Aspect Usage 393 Developing Composite Aspects 397 Adding Behaviors to Existing Members 398 Introducing Interfaces, Methods, Properties and Events 402 Accessing Members of the Target Class 406 Adding Aspects Dynamically 408 Coping with Several Aspects on the Same Target 409 Ordering Advices 412 Understanding Aspect Serialization 413 Aspect Configuration 415 Customizing Aspect Appearance in Visual Studio 417 Customizing Aspect Description in Tooltips 417 Estimating Code Savings 418 Pushing Information to PostSharp Tools Programmatically 419 Consuming Dependencies from an Aspect 421 Using a Global Composition Container 421 Using a Global Service Locator 424 Using Dynamic Dependency Resolution 426 Using Contextual Dependency Resolution 429 Importing Dependencies from the Target Object 432 Validating Architecture 435 Restricting Interface Implementation 437 Controlling Component Visibility Beyond Private and Internal 441 Developing Custom Architectural Constraints 451 Testing and Debugging 459 Debugging Run-Time Logic 461 Debugging Build-Time Logic 465 Testing that an Aspect has been Applied 467 Testing Run-Time Logic 469 Testing Build-Time Logic 471 Hacking 473 Executing Code Just After the Assembly is Loaded 475 6 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 203. • Parent/child relationships: see Parent/Child, Visitor and Disposable on page 239. • Undo/redo: see Undo/Redo on page 255. • Code contracts: see Contracts on page 189. • Logging: see Logging on page 133. 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] publicclass CustomerViewModel { [Required] public Customer Customer { get; set; } publicstring FullName { get { returnthis.Customer.FirstName + " " + this.Customer.LastName; } } } [NotifyPropertyChanged] [Recordable] publicclass Customer { publicstring FirstName { get; set; } publicstring LastName { get; set; } [Child] public AdvisableCollection<Address> Addresses { get; set; } [Url] publicstring HomePage { get; set; } [Log] publicvoid Save(DbConnection connection) { // ... } } [NotifyPropertyChanged] 9 Quick Examples [Recordable] publicclass Address { [Parent] public Customer Parent { get; privateset; } publicstring Line1 { get; set; } } Thread safety patterns Multithreading 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 multithreading. 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 310. • Freezable: see Freezable Threading Model on page 314. • Actor: see Actor Threading Model on page 325. • Reader/Writer Synchronized: see Reader/Writer Synchronized Threading Model on page 319. • Synchronized: see Synchronized Threading Model on page 317. • Thread