本书从最基本的设计原则和准则出发，全方位介绍了设计框架的最佳实践，是微软工程师从.NET Framework开发伊始到现如今的.NET这二十来年间宝贵经验的总结。 与第2版发布时的2008年相比，今天的软件开发范式用翻天覆地来形容也不为过，容器化、云服务、跨平台、DevOps等，都对今天的软件开发者和框架设计者提出了更高的要求。本书对第2版的内容进行了全面的更新，以适应当下发展的潮流。本书虽然是面向.NET平台上的框架设计的，但对其他平台的框架设计同样具有非凡的借鉴价值。通过阅读本书，读者可以了解到如何设计出一个对使用者而言简单、易用且具有一致性的优秀框架。

译者序 首先非常感谢电子工业出版社博文视点提供的宝贵机会，让我可以把这本经典佳作介绍给国内的软件开发者。 所有的软件开发者想必都有一个共同的体会——没有什么开发是可以一蹴而就的，无论是开发框架、组件库还是终端用户程序，开发过程中必然充满权衡和取舍，而如何抉择取舍则依赖于开发者的阅历和经验。这时如果能够有效地借鉴前人的经验，就能少走不少弯路。 这本书是微软内部无数优秀工程师数十年经验和智慧凝结出来的精华，于你我而言，有着非凡的借鉴价值。作者以一致性和易用性为骨，内中的一条条准则为脉络，再用丰富的用例和注解为血肉，将书中内容全方位呈现在我们面前。它让我们了解到，针对不同的 .NET API，它为什么要这么去实现以及它又是如何被实现的，既加深了我们对现有 .NET API 的理解，也为我们指明了框架设计的正确道路。 需要特别说明的是，这本书不是一本教你如何编码的书，内容也不限于 .NET 平台。虽然大多数示例是以 C# 呈现的，但是如果你不是 .NET 程序员，这也完全不会影响你的阅读。如果你不是 .NET 程序员，那么你不需要严格遵循本书的准则，你大可以本书为蓝本，构建出属于你自己或团队的编码规范。如果你碰巧是 .NET 程序员，那么我希望你能够尽可能地遵循这些准则，坚持下来一定能有所回报。 希望本书能够帮助你成为一个更加杰出的程序员，如果中间有什么错漏之处，还请大家批评指正。 最后，感谢我的妻子在我翻译本书时提供的各种支持，既有生活上的，也有情感上的，没有她，我断然无法坚持下来。 王桥 2022年11月，写于苏州 前言 在设计?.NET?平台之初，我们希望它能成为当时最具生产力的企业应用开发平台。在 20 年前，这意味着将“客服端-服务端”架构的应用托管在专用硬件之上。 今天，我们发现自己正置身于行业最大的范式转移之一中：转向云计算。这一转变为企业带来了新的机遇，但对现有的平台来说可能会很棘手，因为开发人员想要开发新型应用程序，导致现有的平台需要去适应由此而来的各种各样的需求。 .NET平台转型相当成功，我认为其中一个主要原因是，我们在设计它的过程中非常小心谨慎，不仅关注生产力、一致性和简单性，还注重确保它能够随着时间的推移不断发展。.NET Core正代表了这种进化，它在云应用开发人员所关心的诸如性能、资源利用率和容器化支持等方面都有显著的提升。 《框架设计指南》第3版新增了许多设计准则，这些准则与?.NET?团队在从“客服端-服务端”应用到云应用这一转变过程中所采取的一系列变更息息相关。 Scott Guthrie 雷德蒙，华盛顿 2020年1月

导论 1 1.1 设计精良的框架的特质 2 1.1.1 设计精良的框架是简单的 2 1.1.2 设计精良的框架设计成本高昂 3 1.1.3 设计精良的框架充满权衡 4 1.1.4 设计精良的框架会借鉴过往经验 5 1.1.5 设计精良的框架旨在不断发展 5 1.1.6 设计精良的框架是完整统一的 6 1.1.7 设计精良的框架是一致的 6 2 框架设计基础 7 2.1 渐进式框架 9 2.2 框架设计基本原则 12 2.2.1 场景驱动设计原则 12 2.2.2 低门槛原则 18 2.2.3 对象模型自文档化原则 22 2.2.4 分层架构原则 27 总结 29 3 命名准则 30 3.1 大小写约定 30 3.1.1 标识符的大小写规则 31 3.1.2 大写首字母缩写词 33 3.1.3 大写复合词和常见术语 36 3.1.4 大小写敏感 38 3.2 通用命名约定 38 3.2.1 词汇选择 39 3.2.2 使用简写和首字母缩写词 41 3.2.3 避免使用特定于编程语言的名称 41 3.2.4 命名现有 API 的新版本 43 3.3 程序集、DLL 和包的命名 45 3.4 命名空间的命名 47 3.4.1 命名空间和类型名称的冲突 48 3.5 类、结构体和接口的命名 50 3.5.1 泛型参数的命名 52 3.5.2 通用类型的命名 52 3.5.3 枚举的命名 53 3.6 类型成员的命名 55 3.6.1 方法的命名 55 3.6.2 属性的命名 55 3.6.3 事件的命名 57 3.6.4 字段的命名 58 3.7 命名参数 59 3.7.1 命名运算符重载参数 59 3.8 命名资源 60 总结 60 4 类型设计准则 61 4.1 类型和命名空间 63 4.2 在类和结构体之间选择 66 4.3 在类和接口之间选择 68 4.4 抽象类设计 75 4.5 静态类设计 76 4.6 接口设计 77 4.7 结构体设计 79 4.8 枚举设计 83 4.8.1 设计标记枚举 89 4.8.2 添加枚举值 92 4.9 嵌套类型 93 4.10 类型和程序集元数据 95 4.11 强类型字符串 97 总结 100 5 成员设计 101 5.1 一般成员设计准则 101 5.1.1 成员重载 101 5.1.2 显式实现接口成员 111 5.1.3 在属性和方法之间选择 114 5.2 属性设计 119 5.2.1 索引属性设计 120 5.2.2 属性变更通知事件 123 5.3 构造函数设计 124 5.3.1 类型构造函数准则 130 5.4 事件设计 132 5.5 字段设计 136 5.6 扩展方法 139 5.7 运算符重载 146 5.7.1 重载 operator== 149 5.7.2 转换运算符 149 5.7.3 比较运算符 151 5.8 参数设计 152 5.8.1 在枚举参数和布尔参数之间选择 154 5.8.2 参数验证 156 5.8.3 参数传递 159 5.8.4 参数数量可变的成员 162 5.8.5 指针参数 165 5.9 在成员签名中使用元组 166 总结 171 6 可扩展性设计 172 6.1 可扩展性机制 172 6.1.1 非密封类 172 6.1.2 受保护的成员 174 6.1.3 事件和回调 175 6.1.4 虚成员 180 6.1.5 抽象（抽象类和接口） 181 6.2 基类 183 6.3 密封 185 总结 187 7 异常 188 7.1 抛出异常 192 7.2 选择抛出正确的异常类型 196 7.2.1 错误消息设计 199 7.2.2 异常处理 200 7.2.3 包装异常 205 7.3 使用标准异常类型 206 7.3.1 Exception和SystemException 206 7.3.2 ApplicationException 207 7.3.3 InvalidOperationException 207 7.3.4 ArgumentException、ArgumentNullException 和 ArgumentOutOfRangeException 207 7.3.5 NullReferenceException、IndexOutOfRangeException 和 AccessViolationException 208 7.3.6 StackOverflowException 208 7.3.7 OutOfMemoryException 209 7.3.8 ComException、SEHException和ExecutionEngineException 210 7.3.9 OperationCanceledException 和 TaskCanceledException 210 7.3.10 FormatException 210 7.3.11 PlatformNotSupportedException 211 7.4 设计自定义异常 211 7.5 异常和性能 212 7.5.1 测试者-执行者模式 212 7.5.2 Try模式 213 总结 216 8 使用准则 217 8.1 数组 217 8.2 特性 220 8.3 集合 223 8.3.1 集合参数 224 8.3.2 集合属性和返回值 225 8.3.3 在数组和集合之间选择 229 8.3.4 实现自定义集合 230 8.4 DateTime 和 DateTimeOffset 231 8.5 ICloneable 233 8.6 IComparable＜T＞ 和 IEquatable＜T＞ 234 8.7 IDisposable 236 8.8 Nullable＜T＞ 236 8.9 Object 237 8.9.1 Object.Equals 237 8.9.2 Object.GetHashCode 238 8.9.3 Object.ToString 240 8.10 序列化 241 8.11 Uri 243 8.11.1 System.Uri 的实现准则 244 8.12 System.Xml 的使用 245 8.13 相等运算符 246 8.13.1 值类型上的相等运算符 248 8.13.2 引用类型上的相等运算符 248 9 通用设计模式 249 9.1 聚合组件 249 9.1.1 面向组件的设计 251 9.1.2 因子类型 253 9.1.3 聚合组件准则 254 9.2 异步模式 256 9.2.1 选择异步模式 256 9.2.2 基于任务的异步模式 258 9.2.3 异步方法的返回类型 263 9.2.4 为现有的同步方法制作一个异步变体 265 9.2.5 异步模式一致性的实现准则 268 9.2.6 经典异步模式 272 9.2.7 基于事件的异步模式 273 9.2.8 IAsyncDisposable 273 9.2.9 IAsyncEnumerable＜T＞ 273 9.2.10 await foreach 的使用准则 274 9.3 依赖属性 276 9.3.1 依赖属性设计 277 9.3.2 附加属性的设计 279 9.3.3 依赖属性校验 280 9.3.4 依赖属性变更通知 280 9.3.5 依赖属性中的值强制 281 9.4 Dispose 模式 282 9.4.1 基本Dispose模式 284 9.4.2 可终结类型 290 9.4.3 限定作用域的操作 293 9.4.4 IAsyncDisposable 296 9.5 工厂 299 9.6 LINQ 支持 303 9.6.1 LINQ 概览 303 9.6.2 实现 LINQ 支持的方法 304 9.7 可选功能模式 309 9.8 协变和逆变 312 9.8.1 逆变 315 9.8.2 协变 316 9.8.3 模拟协变模式 319 9.9 模板方法 321 9.10 超时 323 9.11 XAML 可读类型 324 9.12 操作缓冲 326 9.12.1 数据转换操作 338 9.12.2 向缓冲区中写入固定大小或预定大小的数据 343 9.12.3 使用 Try-Write 模式向缓冲区中写入数据 344 9.12.4 部分写入缓冲区和OperationStatus 348 9.13 最后 353 附录A C#编码风格约定 354 A.1 通用风格约定 355 A.1.1 花括号的使用 355 A.1.2 空格的使用 357 A.1.3 缩进的使用 358 A.1.4 垂直空白 360 A.1.5 成员修饰符 361 A.1.6 其他 362 A.2 命名约定 367 A.3 注释 368 A.4 文件组织 369 附录B 过时的准则 371 B.3 命名准则中的过时准则 371 B.3.8 命名资源 371 B.4 类型设计准则中的过时准则 372 B.4.1 类型和命名空间 372 B.5 成员设计准则中的过时准则 374 B.5.4 事件的设计 374 B.7 异常设计准则中的过时准则 375 B.7.4 设计自定义异常 375 B.8 常见类型使用准则中的过时准则 376 B.8.10 序列化 376 B.9 通用设计模式中的过时准则 383 B.9.2 异步模式 383 B.9.4 Dispose 模式 394 附录C API规范示例 398 附录D 不兼容变更 403 D.1 修改程序集 404 D.1.1 改变程序集的名称（） 404 D.2 添加命名空间 405 D.2.1 添加与现有类型冲突的命名空间（） 405 D.3 修改命名空间 405 D.3.1 修改命名空间的名称或改变大小写（） 405 D.4 移动类型 405 D.4.1 通过 [TypeForwardedTo] 移动类型（） 405 D.4.2 不通过 [TypeForwardedTo] 移动类型（） 406 D.5 删除类型 406 D.5.1 删除类型（） 406 D.6 修改类型 407 D.6.1 密封一个非密封的类型（） 407 D.6.2 解封一个密封类型（） 407 D.6.3 改变类型名称的大小写（） 407 D.6.4 改变类型名称（） 407 D.6.5 改变类型的命名空间（） 408 D.6.6 为结构体添加 readonly 修饰符（） 408 D.6.7 从结构体中移除 readonly 修饰符（） 408 D.6.8 为现有接口添加基接口（） 408 D.6.9 为同一个泛型接口添加第二个声明（） 409 D.6.10 将类变更为结构体（） 409 D.6.11 将结构体变更为类（） 410 D.6.12 将 struct 变更为 ref struct（） 410 D.6.13 将 ref struct 变更为（非ref）struct（） 410 D.7 添加成员 411 D.7.1 通过 new 修饰符掩盖基类成员（） 411 D.7.2 添加抽象成员（） 411 D.7.3 为非密封类型添加成员（） 411 D.7.4 为非密封类型添加覆写成员（） 412 D.7.5 为结构体添加第一个引用类型字段（） 412 D.7.6 为接口添加成员（） 412 D.8 移动成员 413 D.8.1 将成员移动到基类中（） 413 D.8.2 将成员移动到基接口中（） 413 D.8.3 将成员移动到派生类型中（） 413 D.9 删除成员 413 D.9.1 从非密封类型中删除终结器（） 413 D.9.2 从密封类型中删除终结器（） 414 D.9.3 删除非覆写成员（） 414 D.9.4 删除虚拟成员的override（） 414 D.9.5 删除抽象成员的override（） 414 D.9.6 删除或重命名可序列化类型的私有字段（?） 415 D.10 重载成员 415 D.10.1 为成员添加第一个重载（） 415 D.10.2 为引用类型参数添加可选参数重载（?） 416 D.11 更改成员签名 416 D.11.1 重命名方法的参数（） 416 D.11.2 添加或删除方法的参数（） 416 D.11.3 改变方法参数的类型（） 417 D.11.4 重新排列具有不同类型的方法参数（） 417 D.11.5 重新排列具有相同类型的方法参数（） 417 D.11.6 改变方法的返回类型（） 418 D.11.7 改变属性的类型（） 418 D.11.8 将成员的可见性从 public 变更为其他的可见性（） 418 D.11.9 将成员的可见性从 protected 变更为 public（） 419 D.11.10 将虚（或抽象）成员从 protected 变更为 public（） 419 D.11.11 添加或删除 static 修饰符（） 419 D.11.12 改为（或不再）按引用传递参数（） 419 D.11.13 改变按引用传递参数的风格（） 420 D.11.14 为结构体的方法添加 readonly 修饰符（） 420 D.11.15 从结构体的方法中删除 readonly 修饰符（） 420 D.11.16 将必需参数变更为可选参数（） 421 D.11.17 将可选参数变更为必需参数（?） 421 D.11.18 改变可选参数的默认值（） 421 D.11.19 改变常量字段的值（） 421 D.11.20 将抽象成员变更为虚成员（） 422 D.11.21 将虚成员变更为抽象成员（） 422 D.11.22 将非虚成员变更为虚成员（） 422 D.12 改变行为 423 D.12.1 将运行时错误异常变更为使用错误异常（） 423 D.12.2 将使用错误异常变更为有用的行为（） 423 D.12.3 改变方法返回值的类型（?） 423 D.12.4 抛出新的异常类型（） 424 D.12.5 抛出新的异常类型，且它是从现有的异常类型中派生的（） 424 D.13 最后 424