1 Introduction　1
1.1 Qualities of a Well-Designed Framework　3
1.1.1 Well-Designed Frameworks Are Simple　3
1.1.2 Well-Designed Frameworks Are Expensive to Design　4
1.1.3 Well-Designed Frameworks Are Full of Trade-Offs　5
1.1.4 Well-Designed Frameworks Borrow from the Past　5
1.1.5 Well-Designed Frameworks Are Designed to Evolve　5
1.1.6 Well-Designed Frameworks Are Integrated　6
1.1.7 Well-Designed Frameworks Are Consistent　6

2 Framework Design Fundamentals　9
2.1 Progressive Frameworks　11
2.2 Fundamental Principles of Framework Design　14
2.2.1 The Principle of Scenario-Driven Design　15
2.2.2 The Principle of Low Barrier to Entry　21
2.2.3 The Principle of Self-Documenting Object Models　26
2.2.4 The Principle of Layered Architecture　33

3 Naming Guidelines　37
3.1 Capitalization Conventions　38
3.1.1 Capitalization Rules for Identifiers　38
3.1.2 Capitalizing Acronyms　40
3.1.3 Capitalizing Compound Words and Common Terms　43
3.1.4 Case Sensitivity　45
3.2 General Naming Conventions　46
3.2.1 WordChoice　46
3.2.2 Using Abbreviations and Acronyms　48
3.2.3 Avoiding Language-Specific Names　49
3.2.4 Naming New Versions of Existing APIs　51
3.3 Names of Assemblies and DLLs　54
3.4 Names of Namespaces　56
3.4.1 Namespaces and Type Name Conflicts　58
3.5 Names of Classes. Structs. and Interfaces　60
3.5.1 Names of Generic Type Parameters　64
3.5.2 Names of Common Types　64
3.5.3 Naming Enumerations　66
3.6 Names of Type Members　68
3.6.1 Names of Methods　68
3.6.2 Names of Properties　68
3.6.3 Names of Events　70
3.6.4 Naming Fields　72
3.7 Naming Parameters　73
3.7.1 Naming Operator Overload Parameters　74
3.8 Naming Resources　74

4 Type Design Guidelines　77
4.1 Types and Namespaces　79
4.1.1 Standard Subnamespace Names　83
4.2 Choosing Between Class and Struct　84
4.3 Choosing Between Class and Interface　88
4.4 Abstract Class Design　95
4.5 Static Class Design　97
4.6 Interface Design　98
4.7 Struct Design　101
4.8 EnumDesign　103
4.8.1 Designing Flag Enums　110
4.8.2 Adding Values to Enums　114
4.9 Nested Types　115
4.10 Types and Assembly Metadata　118

5 MemberDesign　121
5.1 General Member Design Guidelines　121
5.1.1 Member Overloading　121
5.1.2 Implementing Interface Members Explicitly　128
5.1.3 Choosing Between Properties and Methods　132
5.2 Property Design　138
5.2.1 Indexed Property Design　140
5.2.2 Property Change Notification Events　142
5.3 Constructor Design　144
5.3.1 Type Constructor Guidelines　151
5.4 Event Design　153
5.4.1 Custom Event Handler Design　159
5.5 Field Design　159
5.6 Extension Methods　162
5.7 Operator Overloads　168
5.7.1 Overloading Operator ==　173
5.7.2 Conversion Operators　173
5.8 Parameter Design　175
5.8.1 Choosing Between Enum and Boolean Parameters　177
5.8.2 Validating Arguments　179
5.8.3 Parameter Passing　183
5.8.4 Members with Variable Number of Parameters　186
5.8.5 Pointer Parameters　190

6 Designing for Extensibility　193
6.1 Extensibility Mechanisms　193
6.1.1 Unsealed Classes　194
6.1.2 Protected Members　196
6.1.3 Events and Callbacks　197
6.1.4 Virtual Members　201
6.1.5 Abstractions (Abstract Types and Interfaces)　203
6.2 Base Classes　206
6.3 Sealing　207

7 Exceptions　211
7.1 Exception Throwing　216
7.2 Choosing the Right Type of Exception to Throw　221
7.2.1 Error Message Design　225
7.2.2 Exception Handling　227
7.2.3 Wrapping Exceptions　232
7.3 Using Standard Exception Types　234
7.3.1 Except Con and System Exception　234
7.3.2 Application Exception　234
7.3.3 Invalid Operation Except Con　235
7.3.4 Argument Exception. Argument Null Exception. and Argument Out Of Range Exception　235
7.3.5 Null Reference Exception. IndexOut OfRange Exception. and Access Violation Exception　237
7.3.6 StackOverflowException　237
7.3.7 0utOfMemoryException　238
7.3.8 ComException. SEHException. and ExecutionEngineException　239
7.4 Designing Custom Exceptions　239
7.5 Exceptions and Performance　240
7.5.1 Tester-Doer Pattern　241
7.5.2 Try-Parse Pattern　242

8 Usage Guidelines　245
8.1 Arrays　245
8.2 Attributes　247
8.3 Collections　250
8.3.1 Collection Parameters　252
8.3.2 Collection Properties and Return Values　253
8.3.3 Choosing Between Arrays and Collections　258
8.3.4 Implementing Custom Collections　259
8.4 DateTime and DateTimeOffset　261
8.5 ICloneable　263
8.6 IComparable and IEquatable　264
8.7 IDisposable　266
8.8 Nuiiable　266
8.9 Object　268
8.9.1 Object.EquaLs　268
8.9.2 Object.GetHashCode　270
8.9.3 Object.ToStrlng271
8.10 Serialization　274
8.10.1 Choosing the Right Serialization Technology to Support　275
8.10.2 Supporting Data Contract Serialization　276
8.10.3 Supporting XML Serialization　280
8.10.4 Supporting Runtime Serialization　281
8.11 UrL 283
8.11.1 System. Uri Implementation Guidelines　284
8.12 System.Xml Usage　284
8.13 Equality Operators　286
8.13.1 Equality Operators on Value Types　287
8.13.2 Equality Operators on Reference Types　287

9 Common Design Patterns　289
9.1 Aggregate Components　289
9.1.1 Component-Oriented Design　291
9.1.2 FactoredTypes　294
9.1.3 Aggregate Component Guidelines　295
9.2 The Async Patterns　298
9.2.1 Choosing Between the Async Patterns　298
9.2.2 Classic Async Pattern　300
9.2.3 Classic Async Pattern Basic Implementation Example　304
9.2.4 Event-Based Async Pattern　305
9.2.5 Supporting Out and Ref Parameters　307
9.2.6 Supporting Cancellation　308
9.2.7 Supporting Progress Reporting　309
9.2.8 Supporting Incremental Results　311
9.3 Dependency Properties　312
9.3.1 Dependency Property Design　313
9.3.2 Attached Dependency Property Design　315
9.3.3 Dependency Property Validation　316
9.3.4 Dependency Property Change Notifications　317
9.3.5 Dependency Property Value Coercion　318
9.4 Dispose Pattern　319
9.4.1 Basic Dispose Pattern　322
9.4.2 Finalizable Types　328
9.5 Factories　332
9.6 LINQ Support　337
9.6.1 Overview of LINQ　337
9.6.2 Ways of Implementing LINQ Support　339
9.6.3 Supporting LINQ through IEnumerabLe　339
9.6.4 Supporting LINQ through IOueryabLe　340
9.6.5 Supporting LINQ through the Query Pattern　341
9.7 Optional Feature Pattern　344
9.8 Simulating Covariance　348
9.9 Template Method　354
9.10 Timeouts　356
9.11 XAML Readable Types　358
9.12 And in the End...　361

A C# Coding Style Conventions　363
A.1 General Style Conventions　364
A.1.1 Brace Usage　364
A.1.2 Space Usage　365
A.1.3 Indent Usage　367
A.1.4 Other 367
A.2 Naming Conventions　367
A.3 Comments　368
A.4 File Organization　369

B Using FxCop to Enforce the Framework Design Guidelines　371
B.1 What Is FxCop?　371
B.2 The Evolution of FxCop　372
B.3 How Does It Work?　373
B.4 FxCop Guideline Coverage　374
B.4.1 FxCop Rules for the Naming Guidelines　374
B.4.2 FxCop Rules for the Type Design Guidelines　384
B.4.3 FxCop Rules for Member Design　387
B.4.4 FxCop Rules for Designing for Extensibility　394
B.4.5 FxCop Rules for Exceptions　395
B.4.6 FxCop Rules for Usage Guidelines　397
B.4.7 FxCop Rules for Design Patterns　402

C Sample API Specification　405

Glossary　413
Suggested Reading List　419
Index　423

About the Annotators　437