説明書にCodeを追加する方法

Microsoft Learn に公開した記事にCodeを追加する方法は、スクリーンショット以外に、次のように複数あります：

• 1 行の中にある個々の要素 (単語)。

  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 パッケージの名前は、コードとして処理されます。 明確でない場合は、テキスト書式設定のガイドラインに関するページをご覧ください。

インライン コード スタイル

記事のテキストにコード要素を追加するには、コード スタイルを示すバッククォート (`) でテキストを囲みます。 インライン コード スタイルでは、トリプル バッククォート形式を使用しないでください。

記事がローカライズされる (他の言語に翻訳される) 場合、コードのテキスト スタイルは翻訳されないままになります。 コード スタイルを使用せずにローカライズしないようにするには、「Non-localized strings」 (ローカライズしない文字列) を参照してください。

太字スタイル

一部の古いスタイル ガイドでは、インライン コードには太字を指定しています。 太字は、コード スタイルが目立ってしまい読みやすさが損なわれる場合の選択肢になります。 たとえば、大部分がコード要素の 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>

コード ブロック

ドキュメントにコードを含める構文は、コードの配置場所によって異なります。

• 記事のマークダウン ファイル内にある
• 同じリポジトリのコード ファイル内にある
• 異なるリポジトリのコード ファイル内にある

3 種類のコード ブロックすべてに適用されるガイドラインを次に示します。

• スクリーンショット
• コード検証を自動化する
• コードの主要な行を強調表示する
• 水平スクロール バーを避ける
• 悪いコードを明確に識別する

スクリーンショット

前のセクションに示したメソッドはすべて、使用可能なコード ブロックになります。

• コピーして貼り付けることができます。
• 検索エンジンによってインデックスが作成されます。
• スクリーン リーダーからアクセスできます。

これらは、記事にコードを含める方法として IDE スクリーンショットが推奨されない理由のほんの一部です。 コードに IDE スクリーンショットを使用するのは、IntelliSense のように IDE 自体について何かを示す場合のみです。 色付けや強調表示を示すためだけにスクリーンショットを使用しないでください。

コードの検証

一部のリポジトリには、すべてのサンプル コードを自動的にコンパイルしてエラーをチェックする処理が実装されています。 これは .NET リポジトリによって行われます。 詳細については、.NET リポジトリの「Contributing」 (寄稿) をご覧ください。

別のリポジトリのコード ブロックを挿入する場合は、コードで使用するライブラリの新しいバージョンが出荷されたときに、挿入したコードが壊れたり、古くなったりしないように、コードの保守戦略について所有者と協力します。

強調表示

コンテキストを提供するために、通常、スニペットには必須コード以外も含まれます。 次の例に示すように、スニペット内で注目している主要な行を強調すると、読みやすくなります。

記事のマークダウン ファイルにコードを追加する場合は、コードを強調表示できません。 コード ファイルへの参照によって追加されたコード スニペットに対してのみ、強調表示が有効です。

水平スクロール バー

水平スクロール バーを避けるために、長い行は分割します。 コード ブロック上のスクロール バーは、コードを読みにくくします。 比較的長いコード ブロックでは特に問題になります。このようなブロックでは、スクロール バーと読みたい行を同時に表示できない場合があるためです。

コード ブロックの水平スクロール バーを最小限に抑えるには、85 文字を超えるコード行を分割することをお勧めします。 ただし、スクロール バーの有無は、読みやすさの唯一の条件ではないことに注意してください。 85 文字より前で行を改行すると、読みやすさやコピーおよび貼り付けの利便性が損なわれる場合は、85 文字を超えてもかまいません。

悪いコードを明確に識別する

一部のシナリオでは、回避する必要があるコーディング パターンを指摘することが役立ちます。次に例を示します。

• 試行した場合にコンパイラ エラーが発生するコード。
• 正しくコンパイルされるが、推奨されないコード。

これらのシナリオでは、次のようにできます。

• コード コメントと記事のテキストの両方でそのエラーについて説明します。

  閲覧者は、記事のテキストをスキップし、コードのみを見ている場合が少なくないため、記事のテキストでのみエラーについて説明するのでは不十分です。 また、コード コメントはローカライズされていないので、コード コメントでのみエラーについて説明するのでは不十分です。

• コンパイラ エラーが発生する場合は、コードをコメントアウトします。

  コメントアウトされたコードは、それが記事のリポジトリに現在含まれているか将来実装される場合、その継続的インテグレーション (CI) システムを中断しません。

推奨されていないコードを提示する方法の例については、「Rune の使用例: 大文字と小文字の変更」を参照してください。 この例では、C# メソッド名が ConvertToUpperBadExample であるので、それを回避するアドバイスがコード自体に組み込まれています。

インライン コード ブロック

コード ファイルへの参照によるコード表示が実用的でない場合にのみ、インライン コード ブロックを使用します。 一般に、インライン コードは完全なプロジェクトに含まれるコード ファイルと比較すると、テストして最新の状態に保つことが困難です。 また、インライン コードでは、開発者がコードを理解して使用するのに役立つコンテキストを省略する場合があります。 これらの考慮事項は主にプログラミング言語に適用されます。 インライン コード ブロックは、出力と入力 (JSON など)、クエリ言語 (SQL など)、スクリプト言語 (PowerShell など) にも使用できます。

記事ファイル内のテキスト セクションがコード ブロックであることを示す方法は、トリプル バッククォート (```) でフェンス設定する方法とインデント設定する方法の 2 つがあります。 言語を指定できるので、フェンス設定の使用をお勧めします。 インデントは使用しないようにします。非常に誤解を招きやすく、他の作成者が、記事を編集する必要がある場合に作成時の意図を理解するのが難しくなる可能性があります。

次の例に示すように、言語インジケーターは、開始を示すトリプル バックフォードの直後に配置されます。

マークダウン:

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

表示:

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

言語インジケーターとして使用できる値の詳細については、「Language names and aliases」 (言語名およびエイリアス) をご覧ください。

サポートされていないトリプル バッククォート (```) の後に言語または環境の単語を使用すると、レンダリングされるページのコード セクションのタイトル バーにその単語が表示されます。 可能な場合は、インライン コード ブロックで言語または環境インジケーターを使用します。

リポジトリ内のスニペットの参照

ドキュメントにプログラミング言語のコード スニペットを追加するお勧めの方法は、コード ファイルの参照です。 この方法を使用すると、コード行を強調表示する機能を利用でき、GitHub のより広範囲のスニペットが利用可能になり、開発者が使用できます。 Codeを追加するには、手動で、または Learn 作成 パック を利用して Visual Studio Code 内で、トリプル コロン形式 (:::) を使います。

1. Visual Studio Code で、Alt + M キーまたは Option + M キーをクリックし、[スニペット] を選択します。
2. [スニペット] を選択すると、[Full Search]\(完全な検索\)、[Scoped Search]\(範囲検索\)、または [Cross-Repository Reference]\(リポジトリ間の参照\) の選択を求めるメッセージが表示されます。 ローカルで検索するには、[Full Search]\(完全な検索\) を選択します。
3. 検索用語を入力してファイルを検索します。 ファイルが見つかったら、そのファイルを選択します。
4. 次に、スニペットに含めるコードの行を決定するオプションを選択します。 オプションは ID、Range、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": {}
    },

これで、azure-docs 内のフォルダーであるかのように samples-durable-functions を参照すると、実際には azure-functions-durable-extension リポジトリ内のルート フォルダーを参照するようになります。

Codeを追加するには、手動で、または Learn 作成 パック を利用して Visual Studio Code 内で、トリプル コロン形式 (:::) を使います。

1. Visual Studio Code で、Alt + M キーまたは Option + M キーをクリックし、[スニペット] を選択します。
2. [スニペット] を選択すると、[Full Search]\(完全な検索\)、[Scoped Search]\(範囲検索\)、または [Cross-Repository Reference]\(リポジトリ間の参照\) の選択を求めるメッセージが表示されます。 リポジトリ間で検索するには、[Cross-Repository Reference]\(リポジトリ間の参照\) を選択します。
3. .openpublishing.publish.config.json に含まれているリポジトリの中から選択できるようになります。 リポジトリを選択します。
4. 検索用語を入力してファイルを検索します。 ファイルが見つかったら、そのファイルを選択します。
5. 次に、スニペットに含めるコードの行を決定するオプションを選択します。 オプションは ID、Range、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. マークダウン ファイルで Jupyter ノートブック スニペット構文を使用します。

ノートブックにメタデータを追加する

1. Jupyter ノートブックにセル メタデータを追加して、セルに名前を指定します。

   • Jupyter では、セル ツール バーをまず有効にすることにより セル メタデータを編集できます ([表示] > [セル ツール バー] > [メタデータの編集])。
   • セル ツール バーが有効になったら、名前を付けるセルで [メタデータの編集] を選択します。
   • または、ノートブックの JSON 構造で直接メタデータを編集することができます。

2. セル メタデータに、"name" 属性を追加します。

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

   次に例を示します。

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

   ヒント

   セルがどこで使用されているかを追跡できるように、その他のメタデータを追加できます。 次に例を示します。

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

リポジトリ アクセスを設定する

参照したいノートブック ファイルが別のリポジトリにある場合は、そのコード リポジトリを "依存リポジトリ" として設定します。

Jupyter ノートブック スニペットの構文リファレンス

ノートブックに必要なメタデータが含まれたら、それをマークダウン ファイルで参照します。 ノートブックに追加した <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

対話モードが有効になっている場合、表示されたコード ボックスは [Try It]\(お試し\) または [実行] ボタンを備えています。 次に例を示します。

    ```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 のエクスペリエンスについて、コード ブロックの内容は、次の 3 つのスキャフォールディング エクスペリエンスのどれを選択するかによって異なります。

• スキャフォールディングなし (try-dotnet): このコード ブロックは、フル プログラム テキストを表す必要があります。 たとえば、dotnet new console によって生成される Program.cs ファイルは有効です。 これらは、必要な using ディレクティブなど、小さなプログラム全体を表示する場合に最も役立ちます。 最上位レベルのステートメントは現時点ではサポートされていません。
• メソッド スキャフォールディング (try-dotnet-method): このコード ブロックは、コンソール アプリケーション内の Main メソッドの内容を表す必要があります。 dotnet new console テンプレートによって追加された using ディレクティブを想定できます。 この設定は、1 つの機能を表す短いスニペットに最も役立ちます。
• クラス スキャフォールディング (try-dotnet-class): このコード ブロックは、プログラムのエントリ ポイントとして Main メソッドを持つクラスを表す必要があります。 これらは、クラスのメンバーがどのように対話するかを示すために使用できます。

スニペットの構文リファレンス

構文:

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

• <language> ("省略可能")

  • コード スニペットの言語。 詳細については、この記事で後述する「サポートされている言語」を参照してください。

• <path> ("必須")

  • 参照するコード スニペット ファイルを示す、ファイルシステム内の相対パス。

• <attribute> および <attribute-value> ("省略可能")

  • ファイルからCodeを取得する方法とその表示方法を指定するために併せて使用された：
    • range: 1,3-5 行の範囲。 この例では、行 1、3、4、5 が含まれます。
    • id: Create Code ファイルから挿入する必要があるスニペットの ID です。 この値を範囲と共存させることはできません。
    • highlight: 2-4,6 生成されたコード スニペットで強調表示する必要がある行の範囲や数です。 番号は、ファイルではなく、表示される行 (範囲または ID で指定) からの相対です。
    • interactive: cloudshell-powershell、cloudshell-bash、try-dotnet、try-dotnet-class、try-dotnet-method String 値では、有効にする対話機能の種類を決定します。
    • コード スニペット ソース ファイルでの言語別のタグ名の表記の詳細については、DocFX ガイドラインに関するページを参照してください。

サポートされている言語

Learn 作成 パック には、Code フェンス ブロックに使用できる言語識別子のステートメント入力候補と妥当性確認を提供する機能が含まれています。

フェンスされたコード ブロック

次のステップ

コード以外のコンテンツの種類に対するテキストの書式設定の詳細については、「Text formatting guidelines」 (テキストの書式設定に関するガイドライン) を参照してください。