Introduction 1

1　Qualities of a Well-Designed Framework　3

1.1　Well-Designed Frameworks Are Simple　3

1.2　Well-Designed Frameworks Are Expensive to Design　4

1.3　Well-Designed Frameworks Are Full of Trade-Offs　5

1.4　Well-Designed Frameworks Borrow from the Past　5

1.5　Well-Designed Frameworks Are Designed to Evolve　5

1.6　Well-Designed Frameworks Are Integrated　6

1.7　Well-Designed Frameworks Are Consistent　6

Framework Design Fundamentals 9

1　Progressive Frameworks　11

2　Fundamental Principles of Framework Design　14

2.1　The Principle of Scenario-Driven Design　15

2.2　The Principle of Low Barrier to Entry　21

2.3　The Principle of Self-Documenting Object Models　26

2.4　The Principle of Layered Architecture　33

Naming Guidelines　37

1　Capitalization Conventions　38

1.1　Capitalization Rules for Identifiers　38

1.2　Capitalizing Acronyms　40

1.3　Capitalizing Compound Words and Common Terms　43

1.4　Case Sensitivity　45

2　General Naming Conventions　46

2.1　Word Choice　46

2.2　Using Abbreviations and Acronyms　48

2.3　Avoiding Language-Specific Names　49

2.4　Naming New Versions of Existing APIs　51

3　Names of Assemblies and DLLs　54

4　Names of Namespaces 56

4.1　Namespaces and Type Name Conflicts　58

5　Names of Classes,Structs,and Interfaces 60

5.1　Names of Generic Type Parameters　64

5.2　Names of Common Types　64

5.3　Naming Enumerations　66

6　Names of Type Members 68

6.1　Names of Methods 68

6.2　Names of Properties　68

6.3　Names of Events　70

6.4　Naming Fields 　72

7　Naming Parameters　73

7.1　Naming Operator Overload Parameters　74

8　Naming Resources　74

　Type Design Guidelines　77

1　Types and Namespaces　79

11　Standard Subnamespace Names　83

2　Choosing Between Class and Struct　84

3　Choosing Between Class and Interface　88

4　Abstract Class Design　95

5　Static Class Design 97

6　Interface Design　98

7　Struct Design 101

8　Enum Design　103

8.1　Designing Flag Enums 110

8.2　Adding Values to Enums 114

9　Nested Types 115

10　Types and Assembly Metadata　118

　Member Design 121

1　General Member Design Guidelines 121

1.1　Member Overloading 121

1.2　Implementing Interface Members Explicitly 128

1.3　Choosing Between Properties and Methods 132

2　Property Design 138

2.1　Indexed Property Design 140

2.2　Property Change Notification Events 142

3　Constructor Design 144

3.1　Type Constructor Guidelines 151

4　Event Design 153

4.1　Custom Event Handler Design 159

5　Field Design 159

6　Extension Methods 162

7　Operator Overloads 168

7.1　Overloading Operator== 173

7.2　Conversion Operators 173

8　Parameter Design 175

8.1　Choosing Between Enum and Boolean Parameters 177

8.2　Validating Arguments 179

8.3　Parameter Passing 183

8.4　Members with Variable Number of Parameters 186

8.5　Pointer Parameters 190

　Designing for Extensibility 193

1　Extensibility Mechanisms 193

1.1　Unsealed Classes 194

1.2　Protected Members 196

1.3　Events and Callbacks 197

1.4　Virtual Members 201

1.5　Abstractions(Abstract Types and Interfaces) 203

2　Base Classes 206

3　Sealing 207

　Exceptions 211

1　Exception Throwing 216

2 Choosing the Right Type of Exception to Throw 221

2.1 Error Message Design 225

2.2 Exception Handling 227

2.3 Wrapping Exceptions 232

3 Using Standard Exception Types 234

3.1 Exception and SystemException 234

3.2 ApplicationException 234

3.3 InvalidOperationException 235

3.4 ArgumentException,ArgumentNullException,and ArgumentOutOfRangeException 235

3.5 NullReferenceException,IndexOutOfRangeException,and Access ViolationException 237

3.6 StackOverflowException 237

3.7 OutOfMemoryException 238

3.8 ComException,SEHException,and ExecutionEngine-Exception 239

4 Designing Custom Exceptions 239

5 Exceptions and Performance 240

5.1 Tester-Doer Pattern 241

5.2 Try-Parse Pattern 242

Usage Guidelines 245

1 Arrays 245

2 Attributes 247

3 Collections 250

3.1 Collection Parameters 252

3.2 Collection Properties and Return Values 253

3.3 Choosing Between Arrays and Collections 258

3.4 Implementing Custom Collections 259

4 DateTime and DateTimeOffset 261

5 ICloneable 263

6 IComparable<T> and IEquatable<T> 264

7 IDisposable 266

8 Nullable<T> 266

9 Obiect 268

9.1 Object.Equals 268

9.2 Object.GetHashCode 270

9.3 Object.ToString 271

10 Serialization 274

10.1 Choosing the Right Serialization Technology to Support 275

10.2 Supporting Data Contract Serialization 276

10.3 Supporting XML Serialization 280

10.4 Supporting Runtime Serialization 281

11 Uri 283

11.1 System.Uri Implementation Guidelines 284

12 System.Xml Usage 284

13 Equality Operators 286

13.1 Equality Operators on Value Types 287

13.2 Equality Operators on Refrence Types 287

Common Design Patterns 289

1 Aggregate Components 289

1.1 Component-Oriented Design 291

1.2 Factored Types 294

1.3 Aggregate Component Guidelines 295

2 The Async Patterns 298

2.1 Choosing Between the Async Patterns 298

2.2 Classic Async Pattern 300

2.3 Classic Async Pattern Basic Implementation Example 304

2.4 Event-Based Async Pattern 305

2.5 Supporting Out and Ref Parameters 307

2.6 Supporting Cancellation 308

2.7 Supporting Progress Reporting 309

2.8 Supporting Incremental Results 311

3 Dependency Properties 312

3.1 Dependency Property Design 313

3.2 Attached Dependency Property Design 315

3.3 Dependency Property Validation 316

3.4 Dependency Property Change Notifications 317

3.5 Dependency Property Value Coercion 318

4 Dispose Pattern 319

4.1 Basic Dispose Pattern 322

4.2 Finalizable Types 328

5 Factories 332

6 LINQ Support 337

6.1 Overview of LINQ 337

6.2 Ways of Implementing LINQ Support 339

6.3 Supporting LINQ through IEnumerable<T> 339

6.4 Supporting LINQ through IQueryable<T> 340

6.5 Supporting LINQ through the Query Pattern 341

7 Optional Feature Pattern 344

8 Simulating Covariance 348

9 Template Method 354

10 Timeouts 356

11 XAML Readable Types 358

12 And in the End... 361