SQL 文档的版本控制系统

适用于：SQL ServerAzure SQL 数据库Azure Synapse Analytics

本文介绍了用于 SQL 文档的版本控制系统。 版本控制系统了解产品及其版本。 系统使你能够选择感兴趣的产品和版本。 该系统随后会显示相应的文档。

适用于产品

大多数有关 SQL Server 的文章在标题下方都有 Applies to 字样。 在同一行中，随后列出了一个实用的 SQL 产品列表，并标明该文章是否与相应产品相关。 例如，产品 SQL Server 可以表示为相关，而 Azure SQL 数据库可以表示为与文章无关。

适用范围行并不了解产品版本。 我们会尽力避免适用范围行与版本控制系统配置的产品方面之间的差异。

独立文件集的历史

对于 SQL Server 2014 及更低版本，每个版本都有自己的文档文件的完整单独副本。 例如，SQL Server 2014 的文档最初是作为 SQL Server 2012 文档的副本开始的。 随后，2014 年版文案在产品开发周期中进行了编辑。

这种旧方法意味着如果在 2014 文档中发现了一个漏洞，那么该漏洞也可能存在于 2012 和 2008 文档。 这使得修复缺陷和常规维护变得更加困难。

同一文件中有多个版本

出于此原因和其他原因，SQL Server 2016 的文档文件也适用于 2017、2019，可能还适用于 <vNext>。 这种整合之所以切实可行，是因为我们现在为 SQL Server 文档文件指定了 版本标识。 无论给定文档文件的粒度如何，都可指定或显式嵌入版本控制名字对象。

UI 中的版本控制控件

通过我们的 Docs 网站查看任何 SQL 文档文章时，当前所选的版本标识会显示在目录 (TOC) 上方。 控件是下拉列表。

若要查看不同版本的 SQL Server 的文档，请选择位于当前版本名字对象末尾的扩展器箭头。 然后选择所需的任何产品和版本组合。 选择其他版本时，显示的文档突然发生更改，以显示新选择的版本的差异。 可能有也可能没有任何变化，这两种情况都很常见。

HTTPS 参数 view=

其 Web 地址以 https://learn.microsoft.com/sql/ 开头的每篇文章都有一个名为 ?view= 的参数附加到其地址。 此参数值为版本标识符代码。

https 地址中的名字对象代码始终与版本控制中显示的名字对象名称匹配。

产品，而非版本

版本

在 20 世纪 90 年代和 2000 年代，Microsoft SQL Server 只有一个产品。 每个版本的 SQL Server 都有不同的版本，例如 SQL Server 2008 的开发人员版和企业版 。 这些版本代表的功能集略有不同，但核心产品是相同的。 新的 SQL Server 版本可能仍有各种版本。

产品

随着最近云计算和 Microsoft Azure 的兴起，Microsoft 发布了其 Azure SQL 数据库产品。 虽然传统 SQL Server 本地产品和 Azure SQL 数据库产品共享了很多代码，但这些产品是两个真正独立的产品。

对于 SQL，版本控制名字对象可以区分产品，但不能区分版本。

Azure 云 SQL 产品

对于以 https://learn.microsoft.com/sql/ 开头的文章，几乎所有的 Web 地址都适用于名为 SQL Server 产品的至少一个版本。 这些文章的大部分内容也适用于 Azure 云中托管的一个或多个 SQL 服务产品。 一种这样的 SQL 云产品被命名为 Azure SQL 数据库。

通常，Azure SQL 数据库产品只有一个版本。 几乎所有适用于 Azure SQL 数据库但不适用于 SQL Server 的文章都有以 https://learn.microsoft.com/azure/sql-database/ 开头的 Web 地址。

版本筛选场景

该版本控制机制通过过滤掉所有不适用于当前活动标识符的文档内容来发挥作用。 每次选择不同的版本控制名字对象时，隐藏的内容集都会发生变化。 筛选将隐藏以下级别的内容：

• 文章中的节或句子。
• 目录 (TOC) 中的文章条目。

下面介绍一些场景，说明选择不同名称会产生的影响。

应用场景 1：在当前文章中

以下场景重点关注您当前文章中的各个部分：

1. 当前版本名称是 SQL Server 2017。
2. 你正在阅读一个部分，该部分介绍了首次添加到 SQL Server 版本 2017 的功能。
3. 将名称更改为 SQL Server 2016。
4. 你会注意到你正在阅读的部分已消失。
5. 你又更改了名称，这次改为 SQL Server 2019。
6. 你会注意到正在阅读的 2017 部分已重新显示。

在上述情形中，关于 2017 新功能的部分可能会使用 moniker 范围 进行标记，其中包含以下 moniker 代码：

• >=sql-server-2017

当选择的标识符为 SQL Server 2019 时，版本系统识别到 2019 大于或等于 2017，并显示了该部分。

方案 2：选择指向隐藏文章的链接

以下这一不常见情形说明了：如果您选择当前在目录（TOC）中隐藏的文章链接，会发生什么。 简而言之，该链接有效：

1. 当前的版本标识为 SQL Server 2017。
2. 在当前文章 A中，选择仅适用于 SQL Server 2016 的文章 B 的链接。
   • 在选中该内容之前，目录中对应文章 B 的条目处于隐藏状态。
3. 选择后，将显示文章 B 。
   • 文章 B 的显示强制版本控制切换到 SQL Server 2016 名字对象。
   • 因为必须放弃原始名字 SQL Server 2017。 执行此放弃操作后，网页靠近顶部的位置会显示一条提示消息。 消息说明，为了适应新条目 B，不得不更改当前名称。

应用场景 3：导航到 https 地址

以下文章为 SQL Server 2017 添加了新内容。 本文介绍了在 2017 版中添加到 SQL Server 的功能。 大多数或所有这些新功能也是 2019 版的一部分。 下面是文章的属性。

属性	值
标题	SQL Server 2017 的新增功能
别名范围	=">= sql-server-2017"
https 地址	https://learn.microsoft.com/sql/sql-server/what-s-new-in-sql-server-2017

给定 https 基址，下表说明了当用户使用各种值附加 ?view= 参数后发生的情况。

?view= 的值	https 地址导航行为
（无参数）	版本管理系统会尝试使用其默认的标识名值。 通常我们将其设置为 SQL Server 的最新非预览版本。 SQL Server 2017 或 2019 的默认值将满足属性 >= sql-server-2017。 系统会将参数附加到 https 地址，可能为 ?view=sql-server-2017。 然后将版本控制下拉列表控件设置为匹配名字对象名称。
sql-server-2016	版本控制系统会识别到，该文章的 moniker 范围不包含 2016 版本。 然后，系统会选择其中一个符合该范围要求的名称。 然后，与 2016 版本的情况一样，将附加参数 ?view=，并且控件名称将与参数值匹配。
sql-server-2017	版本系统会识别出该参数值包含在文章的 moniker 范围内。 版本控制将设置为与参数值匹配。
sql-server-2019	与值 sql-server-2017 的情况相同，但参数和控件设置为 2019。

所有 SQL - 不隐藏任何内容的特殊名字对象

All SQL 有一个特殊的产品名称，其唯一的版本是 Hide nothing。 此名称的目的是用于对某些更改进行内部测试。 如果客户使用这一名称，它更可能造成误导，而不是提供信息。

某些文章包含有关多个版本的 SQL Server 信息。 每个常规 moniker 都会隐藏带版本的部分，否则这些部分可能会显示对于该 moniker 版本而言不准确、令人困惑或相互矛盾的信息。 特殊的 All SQL 名称会显示所有版本部分，而用户可能不会明显察觉到显示的信息不准确。

消息：所请求的页面不适用于 <moniker>

以下方案导致在 Docs 网页顶部附近显示信息性消息：

1. 当前版本标识为 SQL Server 2017。
2. 你正在阅读与 SQL Server 2017 相关的文章。
   • 该文章与产品 Azure SQL 数据库无关。
3. 你尝试将名称更改为 Azure SQL 数据库 - current。
4. 你会看到你的尝试被拒绝，并显示一条消息。

此种情况结束时，你会在文档网页顶部附近看到以下信息性消息：

请求的页面不适用于 Azure SQL 数据库 - 当前。 你已重定向到可用于此页的最新产品版本。

最新版本可能排除尚未完全发布且处于预览状态的版本。

SQL Server 的早期版本

版本控制系统已在 SQL Server 2016 及更高版本中全面实现。

• 2012 年及更早版本： 版本控制系统不用于 SQL Server 2012 或更早版本。

  • SQL Server - older 这一特殊名称旨在隐藏几乎所有文章。 极少数例外是旧版本客户可能一次需要几篇文章。
  • 以前版本的 SQL Server 文档

• 2014: SQL Server 2014 的版本控制系统仅实现了一半。 可以在版本控制控件中选择 SQL Server 2014，此方法有效。 然而在内部，2014 的文件专门用于 2014 年，就像 2008 年的文件专用于 2008 年一样。

  • 安装 SQL Server 文档以在 SSMS 中脱机查看

• 2016 及更高版本： SQL Server 2016 及更高版本已完全实现版本控制系统。

  • 欢迎使用 2016 及更高版本的 SQL Server 文档
  • 安装 SQL Server 文档以在 SSMS 中脱机查看

相关内容

• 以前版本的 SQL Server 文档
• SQL Server 文档导航指南
• 如何为 SQL Server 文档做出贡献