如何在檔中包含程序代碼

發行項
01/10/2024

除了螢幕快照之外，還有數種方式可將程式代碼包含在 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	已轉譯
根據預設，Entity Framework 會將名為『Id』或『ClassnameID』的屬性解譯為主鍵。	Entity Framework 預設會將名為 `Id` 或 `ClassnameID` 的屬性解譯為主索引鍵。

對文章進行當地語系化 (翻譯成其他語言) 之後，樣式被設定為程式碼的文字將不會被翻譯。如果您想要在不使用程式碼樣式的情況下防止當地語系化，請參閱不可當地語系化的字串。

粗體樣式

某些較舊的樣式指南會針對內嵌程式碼指定粗體。在程式碼樣式非常突兀並會影響可讀性時，便可以使用粗體。例如，如果 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> 是資源群組，其中...

不建議使用大括弧 { } 作為語法佔位符。它們可能會與可取代文字、格式字串、字串插補、文字範本和類似的程式設計建構中使用的相同表示法混淆。

佔位元名稱可以用連字元分隔（“kebab 大小寫”），底線或完全不分隔（Pascal 大小寫）。 Kebab 案例可能會產生語法錯誤，而且底線可能會與底線衝突。所有上限可能會與許多語言的具名常數衝突，但也可能引起佔位符名稱的注意。

<Resource-Group-Name> 或 <ResourceGroupName>

程式碼區塊

在文件中包含程式碼的語法，會視程式碼所在的位置而有所不同：

位於文章 Markdown 檔案中
位於相同存放庫中的程式碼檔案中
位於不同存放庫中的程式碼檔案中

下列指導方針適用於全部三種類型的程式碼區塊：

截圖
自動化程式代碼驗證
反白顯示程序代碼的主要行
避免水平滾動條
清楚識別不正確的程序代碼

螢幕擷取畫面

上一節所列的所有方法都會產生可使用的程式碼區塊：

您可以複製並貼上這些區塊。
這些區塊均由搜尋引擎編制索引。
螢幕助讀程式可以存取這些區塊。

這些只是不建議使用 IDE 螢幕擷取畫面在文章中包含程式碼的其中幾個原因。只有當您要顯示與 IDE 本身相關的內容時 (例如 IntelliSense)，才使用 IDE 螢幕擷取畫面。單只為了秀出顏色標示和反白顯示，請勿使用螢幕擷取畫面。

程式碼驗證

某些存放庫會實作能自動編譯所有範例程式碼以檢查錯誤的處理程序。 .NET 存放庫就做得到。如需詳細資訊，請參閱 .NET 存放庫中的參與貢獻 \(英文\)。

如果您要包含另一個存放庫中的程式碼區塊，對於這些程式碼的維護策略請與其擁有者合作，讓您包含的程式碼不會因為程式碼所使用的程式庫有了新版本而中斷或過期。

醒目提示

程式碼片段通常會包含比必要程式碼還要多的程式碼，以提供背景內容。在此情況下，若能將程式碼片段中的關鍵程式碼反白顯示，便能協助提升可讀性，如此範例所示：

Example showing highlighted code

當您將程式碼包含在文章 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 Flavored Markdown 支援使用波浪線（~）以及反引號（'）分隔程式代碼區塊。用來開啟和關閉程式代碼區塊的符號必須在相同的程式代碼區塊內保持一致。

對於可作為語言指標使用的值，如需相關資訊，請參閱語言名稱和別名 \(英文\)。

如果您在不支援的三重反桿之後使用語言或環境字組，該字會出現在轉譯頁面上的程式代碼區段標題欄中。盡可能在內嵌程式碼區塊中使用語言或環境指標。

注意

如果您從 Word 檔案複製並貼上程式代碼，請確定它沒有在程式碼中無效的「大引號」。如果有，請將它們變更成一般引號 (' 和 ")。或者，依賴 Learn Authoring Pack，智慧引號取代功能。

存放庫內的程式碼片段參考

想要在文件中包含程式設計語言的程式碼片段，建議透過參考程式碼檔案的方式。這個方法讓您能夠反白顯示一至數行的程式碼，並讓 GitHub 上提供的程式碼片段範圍更廣，以利開發人員使用。您可以使用手動或 Visual Studio Code 中的三個冒號格式來包含程式代碼 :)，以及 Learn Authoring Pack 的協助。

在 Visual Studio Code 中，按一下 Alt + M 或 選項 + M，然後選取 [程式碼片段]。
選取 [程式碼片段] 後，系統會提示您選取 [全文檢索搜尋]、[Scoped Search] \(限定範圍搜尋\) 或 [Cross-Repository Reference] \(跨存放庫參考\)。若要在本機搜尋，選取 [全文檢索搜尋]。
輸入搜尋字詞以尋找檔案。找到檔案之後，請選取檔案。
接下來，選取一個選項以決定應在程式碼片段中包含哪些程式碼。選項包括： 標識碼、範圍和無。
根據您在步驟 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": {}
    },

現在，當您以 azure-docs中資料夾的形式參考 sample-durable-functions 時，實際上是在參考 azure-functions-durable-extension 存放庫中的根資料夾。

您可以使用手動或 Visual Studio Code 中的三個冒號格式來包含程式代碼 :)，以及 Learn Authoring Pack 的協助。

在 Visual Studio Code 中，按一下 Alt + M 或 選項 + M，然後選取 [程式碼片段]。
選取 [程式碼片段] 後，系統會提示您選取 [全文檢索搜尋]、[Scoped Search] \(限定範圍搜尋\) 或 [Cross-Repository Reference] \(跨存放庫參考\)。若要搜尋不同的存放庫，請選取 [Cross-Repository Reference] \(跨存放庫參考\)。
.openpublishing.publish.config.json 會提供您存放庫選項。選取存放庫。
輸入搜尋字詞以尋找檔案。找到檔案之後，請選取檔案。
接下來，選取一個選項以決定應在程式碼片段中包含哪些程式碼。選項包括： 標識碼、範圍和無。
根據您在步驟 5 中的選擇提供值。

您的程式碼片段參考看起來如下：

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

在 azure-functions-durable-extension 存放庫中，該程式碼檔案是位於 samples/csx/shared 資料夾中。如先前所述，反白顯示行的行號是相對於程式碼片段開頭，而不是檔案的開頭。

注意

您指派給相依存放庫的名稱相對於主要存放庫的根目錄，但 tilde （~）是指 docset 的根目錄。 docset 根目錄是由 build_source_folder 中的 .openpublishing.publish.config.json決定。在上述範例中，程式碼片段的路徑適用於 azure-docs 檔存放庫，因為 build_source_folder 是指存放庫根目錄 (.)。如果 build_source_folder 是 articles，路徑的開頭會是 ~/../samples-durable-functions，而不是 ~/samples-durable-functions。

Jupyter Notebook 中的代碼段

您可以將 Jupyter 筆記本中的儲存格參考為代碼段。若要參考儲存格：

將儲存格元數據新增至筆記本，以取得您想要參考的儲存格。
設定存放庫的存取權。
在您的 Markdown 檔案中使用 Jupyter Notebook 代碼段語法。

將元數據新增至筆記本

藉由在 Jupyter 筆記本中新增儲存格元數據來命名單元格。
- 在 Jupyter 中，您可以先啟用資料格工具列來編輯儲存格元數據： 檢視 > 儲存格工具列 > 編輯元數據。
- 啟用儲存格工具列之後，請選擇您想要命名之儲存格上的[ 編輯元數據 ]。
- 或者，您可以直接在筆記本的 JSON 結構中編輯元數據。
在儲存格元數據中，新增「name」屬性：
```
"metadata": {"name": "<name>"},
```
例如：
```
"metadata": {"name": "workspace"},
```
提示

您可以新增任何其他您想要的元數據，以協助您追蹤使用儲存格的位置。例如：
```
    "metadata": {
      "name": "workspace",
      "msdoc": "how-to-track-experiments.md"
    },
```

設定存放庫存取權

如果您想要參考的筆記本檔案位於不同的存放庫中，請將程式代碼存放庫設定為相依存放庫。

Jupyter Notebook 代碼段語法參考

當您的筆記本包含必要的元數據之後，請在 Markdown 檔案中參考它。 <cell-name-value>使用您新增至筆記本的，以及<path>您設定為相依存放庫的。

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

例如：

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

重要

此語法是區塊 Markdown 延伸。必須用於本身的行。

針對標識碼使用任何支持的語言<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 - 以類別 Scaffolding 啟用 Try .NET
try-dotnet-method - 以方法 Scaffolding 啟用 Try .NET

以下列出一些範例：

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

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