宣布在 docs.microsoft.com 上推出统一的 .NET 引用体验

本文作者：Jeff Sandquist，Azure Growth 和 Ecosystem 团队总经理。

大约在一年前，我们试验性地在 docs.microsoft.com 上发布了 .NET Core 参考文档。 今天，我们非常高兴地宣布推出我们统一的 .NET API 参考体验。 我们理解开发人员的工作效率是关键 - 从业余开发人员到初创公司，再贯穿到企业。 考虑到这一点，我们与 Xamarin 团队密切合作，以标准化我们在 Microsoft 记录、发现和导航 .NET API 的方式。

所有 .NET 文档都在同一个位置

以前，如果你想找到 Microsoft 提供的基于 .NET 的 SDK，必须花一些时间使用你最喜欢的搜索引擎，试图找到可以下载它的地方，以及发现相关的 API 文档。

今后，我们计划将所有与 .NET 兼容的 SDK 统一放在一个位置，方便用户搜索：https://docs.microsoft.com/dotnet/api。 在那里，你将找到 .NET Framework、.NET Core、.NET Standard 和 Xamarin 的参考文档，以及我们的 Azure NuGet 包的文档。 在接下来的几个月中，我们将为此体验添加更多 SDK。

API 浏览器简介

我们的主要目标是引入类似 IntelliSense 的体验，从 Web 浏览器搜索所有 .NET API。 可以通过直接在 API 浏览器页面中键入完整名称或部分名称来搜索命名空间、类、方法或接口。

如果你不确定具体类型、成员或命名空间属于哪个 SDK，只需在 API 范围下拉列表中选择“所有 API”，然后搜索所有可用的参考文档。或者，如果想要限制搜索，可以选择一个具体框架或 SDK 及其版本（例如 .NET Framework 4.7），然后仅在该 API 集内进行搜索。

API 浏览器体验也集成在基于 .NET 的 API 的目录顶部，无论你在参考文档中的哪个位置，都可以快速找到任何 API：

一旦你进入一个特定的命名空间，API 浏览器的范围就只限于连接在一起的 API 系列，因此你的搜索始终会根据你的上下文返回最佳结果。

版本控制支持

你不再需要知道某个类型在 .NET Framework 或 Azure Storage NuGet 包的特定版本中是否有可用的成员，只需从 API 浏览器控件中更改版本，内容将会相应地调整：

构建时考虑开放源代码

为了构建 API 浏览器，我们使用了开放标准和工具。 在其核心，我们利用了 DocFX（开放的文档生成工具链），以及 Xamarin 的 mdoc 应用程序。

现在，我们的所有托管参考文档都是通过 NuGet 随附的二进制文件自动生成的，或者是主要框架发行版的一部分，例如 .NET Framework 或 .NET Core。

使用持续集成基础结构，我们可以获得最新 API 的准确文档，这些文档现在可以在发布后数小时内公开，并开放接受贡献。 我们还将所有 .NET API 文档标准化为 ECMAXML 格式，无论记录的 SDK 是什么，它都会创建一致且全面的 API 表示形式。 而且，你不需要知道复杂的文件格式，因为你可以在 Markdown 中提供可嵌入到自动生成的文档中的内容。参考文档的社区贡献将在下个月内启用。

专注于内容

除了新的体验之外，我们还对参考内容进行了优化，使其更易于发现和阅读。 我们已将目录更新为始终以命名空间为焦点。 无论是浏览有关命名空间、类型还是成员的信息，我们始终只显示父命名空间及其所有子类型 & 各自的分组成员：

这意味着参考页面是整洁的，并且首先显示最重要的信息（例如一般概述和示例），一切一目了然。

你还会从一开始就看到与你相关的示例，它们根据你选择的编程语言进行了筛选，你不必再滚动到页面的最底部来寻找这些示例。

通过反馈驱动

这只是我们改进参考文档体验的开始。 我们想要倾听你的反馈，了解我们如何使我们的文档更具吸引力、更有用，并尽快为你提供帮助。 请访问我们的 UserVoice 网站，并告诉我们可以如何改进 API 浏览器体验。 你还可以在 Twitter 上通过 @docsmsft 随时联系我们，以获得快速更新。