.NET API 文档已从 MSDN 移至 docs.microsoft.com
本文由云与 AI 部门项目经理 Den Delimarsky 撰写。
我们非常高兴地宣布，11 个区域设置的所有 .NET Framework 文档已完成从 MSDN 到 docs.microsoft.com 的迁移。 说到这项迁移的数量和规模，.NET Framework 内容相当于超过 900 万个 API 文档，占整个 MSDN 库容量的 20%。
我们的目标是在用户查找和导航 Microsoft 提供的所有 .NET API 时提供统一、现代化且一致的体验，包括对版本控制的深度支持、使用和运行 API 代码示例、通过自动化轻松启用 API 更新以及支持社区贡献。
docs.microsoft.com 针对以下内容提供这种体验：
- .NET Framework（版本 1.1 - 4.7.2）
- .NET Core（版本 1.0 - 2.1）
- .NET Standard（版本 1.0 - 2.0）
- 以及 Microsoft 提供的所有 .NET API、SDK 和 NuGet 包
在一个位置通过 .NET API 浏览器搜索所有 Microsoft .NET API
你是否曾经想寻找一个 API，却不知道从何处着手？ 我们构建了一个专用 API 搜索索引，让你能够在几秒钟内使用产品和版本筛选器快速找到所需的 API - .NET API 浏览器。
版本控制支持
你不再需要知道某个类型在 .NET Framework 或 Azure Storage NuGet 包的特定版本中是否有可用的成员，只需从 API 浏览器控件中更改版本，内容将会相应地调整：
组织方式已改进
在左侧的目录中，按命名空间和该命名空间中的实体类型对内容进行了分组。 例如，当你选择一个类时，会看到实体按各自的类型进行了分组：属性、字段、方法和事件。
另外，还可以在 .NET API 浏览器的帮助下进行搜索，甚至可以筛选出具体的 API 版本，所有这些都来自目录，让你轻松找到所需的确切 API。
客户还告诉我们，位于 API 参考页面中时，有时很难找到 API 的下载、设置和其他有用文档。 如下图所示，Azure .NET SDK 将文章和参考文档都合并在一个目录中！
直观的 URL
最初推出 docs.microsoft.com 时，我们的一个目标就是提供清晰、一致且直观的分层 URL。 回想一下使用 MSDN 时的情形，某些 .NET URL 的结构如下所示：
https://msdn.microsoft.com/library/8kszeddc(v=vs.110).aspx
如果只是看一眼，真的很难了解内容是什么。
上述链接现在变为：
https://docs.microsoft.com/dotnet/api/system.array.sort
下面只是“URL 手册”中的一些 URL 规则，用于确保 .NET 具有一致且直观的 URL：
命名空间
模式：https://docs.microsoft.com/{locale}/dotnet/api/{namespace}
示例：https://docs.microsoft.com/dotnet/api/system.collections.generic/
类
模式：https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}
示例：https://docs.microsoft.com/dotnet/api/system.flagsattribute
方法
模式：https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}
示例：https://docs.microsoft.com/dotnet/api/system.decimal.add
示例优先
我们从与客户的访谈中了解到的一个一致的观点是，高质量、简洁且功能正常的 API 代码实例是非常重要的。 在 MSDN 中，示例位于页面的末尾，这意味着，在某些示例中，需要向下滚动 20 多次，才能看到某个类型的第一个示例。 在 Docs 中，示例会首先显示，如下所示：
与 MSDN 一样，Docs 也支持所有 .NET 语言，包括 C#、VB、F# 和 C++
在浏览器中以交互方式运行示例
在处理代码时，学习的最佳方式是实际编写代码，我们想确保你能从浏览器中实现它。 一年前，我们推出了“试用 .NET”功能，并在这一年中将该功能整合到了许多文章中。 今后，我们还会继续将此功能整合到更多的 API 文档中，让你无需离开页面即可进行试验。
通过标准自动生成工具提供支持
docs.microsoft.com 上的所有 API 文档都是自动生成的，因此我们可以轻松地记录整个 API 图面，大大缩短了更新的时间和频率，从几周缩短到几分钟。 这可以确保所有 .NET API 都有高质量的 API 文档。
为此，我们与 Xamarin 工程团队合作开发，并使用 mdoc 生成所有 .NET 参考文档。
MSDN 链接 - 重定向到 docs.microsoft.com
在开始迁移时，我们想确保不破坏任何链接 - 在标准 301 重定向的帮助下，所有这些 MSDN 链接都可以整合到产品中，博客文章和其他网站应能正常工作，并将用户指向新位置。
准备好为社区做出贡献
所有迁移的内容现在都是开源的，位于 GitHub 上的 dotnet/dotnet-api-docs 存储库中。 但在进行贡献时不必搜索文件，只需转到任一 .NET API 页面并单击“编辑”，就会直接转到要更改的文件。
