.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 页面并单击“编辑”,就会直接转到要更改的文件。