如何在文档中包含代码

除了屏幕截图，还可通过以下几种方法在发布到 Microsoft Learn 的文章中包含代码：

• 一行中的单个元素（单词）。

  以下是 code 样式的示例。

  在文本中引用附近代码块中的命名参数和变量时，使用代码格式。 代码格式也可用于属性、方法、类和语言关键字。 有关详细信息，请参阅本文后面的代码元素。

• 文章 Markdown 文件中的代码块。

      ```csharp
      public static void Log(string message)
      {
          _logger.LogInformation(message);
      }
      ```
  

  不能通过引用代码文件来显示代码时，使用内联代码块。 有关详细信息，请参阅本文后面的代码块。

• 通过引用本地存储库中的代码文件的代码块。

  :::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
  

  有关详细信息，请参阅本文后面的存储库内的片段引用。

• 通过引用另一存储库中的代码文件的代码块。

  :::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
  

  有关详细信息，请参阅本文后面的存储库外的片段引用。

• 允许用户在浏览器中执行代码的代码块。

  :::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
  

  有关详细信息，请参阅本文后面的交互式代码片段。

除了解释包含代码的每种方法的 Markdown 之外，本文还提供了一些适用于所有代码块的一般指南。

代码元素

“代码元素”指的是编程语言关键字、类名、属性名称等。 什么内容可以称为代码，并不总是显而易见。 例如，NuGet 包名称应被视为代码。 如有疑问，请参阅文本格式设置准则。

内联代码样式

若要在文章文本中包含代码元素，请使用反引号 (`) 将其引起来，表示代码样式。 内联代码样式不得使用三个反引号格式。

在本地化文章（翻译成其他语言）时，不会翻译代码样式的文本。 如果要在不使用代码样式的情况下防止本地化，请参阅非本地化字符串。

粗体样式

一些较旧的风格指南为内联代码指定粗体格式。 当代码样式太过突兀以致于影响可读性时，可以选择使用粗体。 例如，主要包含代码元素的 Markdown 表格如果全部应用代码样式，可能看起来杂乱。 如果选择使用粗体样式，请使用非本地化字符串语法以确保代码未本地化。

链接

在某些上下文中，指向参考文档的链接可能比代码格式更有帮助。 如果使用链接，请勿将代码格式应用于链接文本。 将链接设置为代码会掩盖文本是链接的事实。

如果使用链接，并且之后在相同的上下文中引用同一元素，请对后面的实例应用代码格式而非链接。 例如：

The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.

呈现：

此文本中对 System.CommandLine 的第一个引用是链接。 对 System.CommandLine 的后续引用可以是代码样式。

占位符

如果希望用户使用其自己的值替换一段显示的代码，请使用由尖括号标记的占位符文本。 例如：

az group delete -n <ResourceGroupName>

你可能会注意到，在替换实值时必须删除尖括号。 Microsoft 写作风格指南要求使用斜体，你可以在带尖括号的内联代码中设置格式：

<ResourceGroupName> 是资源组，其中...

建议不要将大括号 { } 用作语法占位符。 它们可能会与可替换文本、格式字符串、字符串内插、文本模板和类似的编程构造中使用的相同表示法混淆。

占位符名称可以使用连字符分隔（“短横线隔开式”），也可以用下划线分隔，也可以完全不分隔（帕斯卡命名法）。 短横线隔开式可能会生成语法错误，下划线可能会与强调划线冲突。 所有大写可能与多种语言中的命名常量冲突，但也可能引起对占位符名称的注意。

<Resource-Group-Name> 或 <ResourceGroupName>

代码块

用于将代码包含在文档中的语法取决于代码所在的位置：

• 在文章的 Markdown 文件中
• 在同一个存储库的代码文件中
• 在不同存储库的代码文件中

下面是适用于所有三种类型代码块的指导原则：

• 屏幕截图
• 自动执行代码验证
• 突出显示关键代码行
• 避免水平滚动条
• 清晰识别错误代码

屏幕截图

上一部分中列出的所有方法均可生成可用的代码块：

• 可从中进行复制和粘贴。
• 可通过搜索引擎将其编入索引。
• 屏幕阅读器可访问这些代码块。

这只是建议不要将 IDE 屏幕截图作为在文章中包含代码的方法的一些原因。 仅当显示 IDE 本身的相关信息（如 IntelliSense）时，才将 IDE 屏幕截图用于代码。 请勿仅将屏幕截图用于显示着色和突出显示。

代码验证

一些存储库已经实现了自动编译所有示例代码以检查错误的过程。 .NET 存储库已实现此过程。 有关详细信息，请参阅 .NET 存储库中的参与。

如果要包含其他存储库中的代码块，请与所有者共同制定代码维护策略，以便在提供代码使用的新版本的库时，你包含的代码不会中断或过期。

Highlighting

代码段通常包含提供上下文所需的更多代码。 在代码段中突出显示所关注的关键行时，它有助于提高可读性，如本例所示：

将代码包含在文章的 Markdown 文件中时，将无法突出显示代码。 它只适用于通过引用代码文件包含的代码段。

水平滚动条

分解较长的行，以避免水平滚动条。 代码块上的滚动条为阅读代码带来困难。 在更长的代码块上尤其会出现此问题，在其中可能无法看到滚动条和同时想要读取的行。

要尽量使代码块上的水平滚动条保持最小，一种很好的做法是分解超过 85 个字符的代码行。 但请记住，滚动条存在与否不是衡量可读性的唯一标准。 如果在不到 85 个字符时换行，会影响可读性或复制粘贴的便捷性，因此请随意超过 85 个字符。

清晰识别错误代码

在某些情况下，指出应避免的编码模式很有帮助，例如：

• 如果尝试将导致编译器错误的代码。
• 将正确编译但不推荐的代码。

针对这些情况：

• 解释代码注释和文章文本中的错误。

  读者通常会跳过文章文本并仅查看代码，因此仅解释文章文本中的错误是不够的。 仅仅在代码注释中解释错误也是不够的，因为代码注释未本地化。

• 如果会导致编译器错误，请考虑注释掉代码。

  如果文章的存储库现在有一个持续集成 (CI) 系统或将来实现一个持续集成系统，则注释掉的代码不会损害持续集成系统。

有关如何显示不推荐的代码的示例，请参阅 Rune 用法示例：更改字母大小写。 在此示例中，相关避免建议甚至内置于代码本身，因为 C# 方法名称为 ConvertToUpperBadExample。

内联代码块

仅当不能通过引用代码文件来显示代码时，才使用内联代码块。 与代码文件（完整项目的一部分）相比，内联代码通常更难测试且更难保持最新。 并且内联代码可能忽略可帮助开发人员理解和使用代码的上下文。 这些注意事项主要适用于编程语言。 内联代码块还可用于输出和输入（如 JSON）、查询语言（如 SQL）和脚本语言（如 PowerShell）。

可以通过以下两种方法在文章文件中指出文本的一部分是一个代码块：使用三个反引号 (```) 将其隔开或缩进。 隔离是首选方法，因为它允许指定语言。 避免使用缩进，因为这样极易出错，并且当其他编写者需要编辑你的文章时，可能很难理解你的意图。

语言指示紧跟开头的三个反斜杠后，如以下示例所示：

Markdown：

    ```json
    {
        "aggregator": {
            "batchSize": 1000,
            "flushTimeout": "00:00:30"
        }
    }
    ```

呈现：

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}

有关可以用作语言指示的值的信息，请参阅语言名称和别名。

如果在三个反引号 (```) 后面使用不受支持的语言或环境文字，该文字会显示在呈现页面上的代码部分标题栏中。 请尽量在内联代码块中使用语言或环境指示。

存储库内的代码段引用

要在文档中包含用于编程语言的代码片段，首选方法是引用代码文件。 借助此方法，你可以突出显示几行代码，并在 GitHub 上提供更广泛的代码片段上下文供开发人员使用。 可手动使用三冒号格式 (:::) 或在 Visual Studio Code 中借助 Learn 创作包来包含代码。

1. 在 Visual Studio Code 中，单击 Alt + M 或 Option + M，再选择“片段”。
2. 选择片段后，系统将提示你进行完全搜索、范围搜索或跨存储库引用。 要在本地搜索，请选择“完整搜索”。
3. 要查找文件，请输入搜索词。 找到文件后，将其选中。
4. 接下来，选择一个选项来确定应在片段中包含哪些代码行。 选项包括：ID、范围 和 None。
5. 根据在步骤 4 中选择的设置，必要时提供一个值。

显示整个代码文件：

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::

通过指定行号来显示代码文件的一部分：

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

通过指定一个代码段名称来显示代码文件的一部分：

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

以下部分说明了这些示例：

• 使用代码文件的相对路径
• 只包括选定行号
• 参考命名的代码段
• 突出显示选定行

有关详细信息，请查看本文后面的片段语法引用。

代码文件路径

示例：

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

本示例摘自 ASP.NET 文档存储库，aspnetcore/data/ef-mvc/crud.md 文章文件。 此代码文件通过同一存储库中的 aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs 相对路径进行引用。

选定行号

示例：

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

此示例仅显示了 StudentController.cs 代码文件中的第 2-24 行和第 26 行。

更倾向于命名的代码片段而不是硬编码的行号，如下一部分所述。

命名的代码段

示例：

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

仅在名称中使用字母和下划线。

本示例显示代码文件的 snippet_Create 部分。 本示例的代码文件在 C# 代码中注释中带有代码片段标记：

// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet

可以嵌套命名代码片段，如以下示例所示：

// <Method>
public static void SomeMethod()
{
    // <Line>
    // Single line of code.
    // </Line>
}
// </Method>

呈现 Method 代码片段时，Line 标记不包含在呈现的输出中。

在可能的情况下，请参考命名的部分，而不是指定行号。 行号引用不太稳妥，因为在更改行号时，代码文件不可避免地会发生更改。 不一定会收到此类更改的通知。 最终，文章开始显示错误行，并且你完全不知道发生的任何变更。

突出显示选定行

示例：

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5":::

本示例突出显示第 2 行和第 5 行，从显示的代码段开头开始计数。 要突出显示的行号并不从代码文件的开头开始计数。 也就是说，代码文件的第 3 行和第 6 行会突出显示。

存储库外的代码段引用

如果要引用的代码文件在另一个存储库中，请将代码储存库设置为“从属存储库”。 在执行此操作时，请为它指定一个名称。 然后，该名称会作为一个文件夹名称用于代码引用。

例如，文档存储库是 Azure/azure-docs，代码存储库是 Azure/azure-functions-durable-extension。

在 azure-docs 的根文件夹中，在 .openpublishing.publish.config.json 中添加以下部分：

    {
      "path_to_root": "samples-durable-functions",
      "url": "https://github.com/Azure/azure-functions-durable-extension",
      "branch": "main",
      "branch_mapping": {}
    },

现在，当你引用 sample-durable-functions（如同它是 azure-docs 中的一个文件夹）时，你实际上引用的是 azure-functions-durable-extension 存储库中的根文件夹。

可手动使用三冒号格式 (:::) 或在 Visual Studio Code 中借助 Learn 创作包来包含代码。

1. 在 Visual Studio Code 中，单击 Alt + M 或 Option + M，再选择“片段”。
2. 选择片段后，系统将提示你进行完全搜索、范围搜索或跨存储库引用。 要跨存储库进行搜索，请选择“跨存储库引用”。
3. 将显示 .openpublishing.publish.config.json 中的存储库供你选择。 选择存储库。
4. 要查找文件，请输入搜索词。 找到文件后，将其选中。
5. 接下来，选择一个选项来确定应在片段中包含哪些代码行。 选项包括：ID、范围 和 None。
6. 根据在步骤 5 中选择的设置，提供一个值。

你的片段引用将如下所示：

:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::

在 azure-functions-durable-extension 存储库中，该代码文件位于 samples/csx/shared 文件夹中。 如前所述，突出显示的行号对应于代码片段的开头而非文件的开头。

Jupyter 笔记本中的代码片段

可以将 Jupyter 笔记本中的单元格作为代码片段引用。 若要引用单元格：

1. 针对要引用的单元格，将单元格元数据添加到笔记本。
2. 设置对存储库的访问权限。
3. 在 markdown 文件中使用 Jupyter 笔记本代码片段语法。

将元数据添加到笔记本

1. 通过在 Jupyter 笔记本中添加单元格元数据来命名单元格。

   • 在 Jupyter 中，可以通过首先启用单元格工具栏来编辑单元格元数据：“查看”>“单元格工具栏”>“编辑元数据”。
   • 启用单元格工具栏后，选择要命名的单元格上的“编辑元数据”。
   • 或者，可以在笔记本的 JSON 结构中直接编辑元数据。

2. 在“单元格元数据”中，添加“名称”属性：

   "metadata": {"name": "<name>"},
   

   例如：

   "metadata": {"name": "workspace"},
   

   提示

   可以添加任何其他用于帮助跟踪单元格使用位置的元数据。 例如：

       "metadata": {
         "name": "workspace",
         "msdoc": "how-to-track-experiments.md"
       },
   

设置存储库访问权限

如果要引用的笔记本文件在另一个存储库中，请将代码储存库设置为从属存储库。

Jupyter 笔记本代码片段语法参考

笔记本包含所需的元数据后，请在 markdown 文件中引用它。 使用添加到笔记本的 <cell-name-value>，并使用设置为依赖存储库的 <path> 。

[!notebook-<language>[] (<path>/<notebook-name.ipynb>?name=<cell-name-value>)]

例如：

[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]

将任何受支持的语言用于 <language> 标识符。

交互式代码片段

内联交互式代码块

对于以下语言，可以在浏览器窗口中执行代码段：

• Azure Cloud Shell
• Azure PowerShell Cloud Shell
• C# REPL

启用交互模式后，呈现的代码框会出现“尝试”或“运行”按钮。 例如：

    ```azurepowershell-interactive
    New-AzResourceGroup -Name myResourceGroup -Location westeurope
    ```

呈现为：

New-AzResourceGroup -Name myResourceGroup -Location westeurope

且

    ```csharp-interactive
    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");
    ```

呈现为：

    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");

要为特定代码块启用此功能，请使用特殊的语言标识符。 可用选项包括：

• azurepowershell-interactive - 启用 Azure PowerShell Cloud Shell，如前例所示
• azurecli-interactive - 启用 Azure Cloud Shell
• csharp-interactive - 启用 C# REPL

对于 Azure Cloud Shell 和 PowerShell Cloud Shell，用户可以只针对自己的 Azure 帐户运行命令。

通过引用包含的代码片段

可以为通过引用包含的代码段启用交互模式。 要为特定代码块启用此功能，请使用 interactive 属性。 可用的属性值如下：

• cloudshell-powershell - 启用 Azure PowerShell Cloud Shell，如前例所示
• cloudshell-bash - 启用 Azure Cloud Shell
• try-dotnet - 启用 Try .NET
• try-dotnet-class - 使用类基架启用 Try .NET
• try-dotnet-method - 使用方法基架启用 Try .NET

以下是一些示例：

:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::

:::code source="Bash.sh" interactive="cloudshell-bash":::

对于 Azure Cloud Shell 和 PowerShell Cloud Shell，用户只能针对自己的 Azure 帐户运行命令。

对于 .NET Interactive 体验，代码块的内容取决于三种基架体验中所选的体验：

• 无基架 (try-dotnet)：代码块应表示完整的程序文本。 例如，dotnet new console 生成的 Program.cs 文件将有效。 这些最适用于显示整个小程序，包括所需的 using 指令。 此时不支持顶级语句。
• 方法基架 (try-dotnet-method)：代码块应表示控制台应用程序中的 Main 方法的内容。 你可以假设由 dotnet new console 模板添加的 using 指令。 此设置最适用于演示一个功能的短代码段。
• 类基架 (try-dotnet-class)：代码块应将具有 Main 方法的类表示为程序入口点。 这些可用于显示类的成员如何交互。

片段语法引用

语法：

:::code language="<language>" source="<path>" <attribute>="<attribute-value>":::

• <language>（可选）

  • 代码片段的语言。 有关详细信息，请参阅本文后面的支持的语言部分。

• <path>（强制）

  • 文件系统中的相对路径指示要引用的代码片段文件。

• <attribute> 和 <attribute-value>（可选）

  • 配合使用以指定如何从文件中检索代码以及如何显示代码：
    • range: 1,3-5 行的范围。 此示例包括第 1、第 3、第 4 和第 5 行。
    • id：Create 需要从代码文件中插入的片段的 ID。 该值不能与范围共存。
    • highlight：2-4,6 需要在生成的代码片段中突出显示的范围和/或行数。 该编号对应于显示的行数（由范围或 ID 指定）而非文件。
    • interactive：cloudshell-powershell、cloudshell-bash、try-dotnet、try-dotnet-class、try-dotnet-method 字符串值确定启用了哪些类型的交互。
    • 有关代码片段源文件中的标记名称表示形式（按语言）的详细信息，请参阅 DocFX 指南。

支持的语言

Learn 创作包包含一项功能，可对代码隔离块的可用语言标识符提供语句完成和验证功能。

隔离代码块

后续步骤

要了解内容类型（代码除外）的文本格式设置，请参阅文本格式设置准则。