📄

AdaptiveCards.Templating でアダプティブ カードを生成する

に公開
C#
tech

はじめに

C# からアダプティブ カードを生成する方法は 2 種類あります。

似たようなパッケージですが、機能的には大きく異なります。中でも影響があるのは内部で参照する JSON ライブラリです。AdaptiveCards SDK は Newtonsoft.Json を、AdaptiveCards Templating SDK は System.Text.Json を参照しています。最近では System.Text.Json を使用する場合が増えているため、AdaptiveCards Templating SDK を積極的に使うことをおすすめします。

https://learn.microsoft.com/ja-jp/adaptive-cards/templating/sdk?WT.mc_id=M365-MVP-5002941

サンプル コード

https://github.com/karamem0/samples/tree/main/adaptive-cards-template

実行手順

基本的な流れ

AdaptiveCards Templating SDK ではテンプレート化されたアダプティブ カード JSON を読み込み、データをバインドします。バインドする値は ${変数名} という形式で宣言します。$root、$data、$index といった予約済みのキーワードも使用できます。

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.6",
  "body": [
    {
      "type": "TextBlock",
      "text": "${title}",
      "wrap": true,
      "style": "heading"
    },
    {
      "type": "FactSet",
      "facts": [
        {
          "title": "Name",
          "value": "${customer[0].firstName} ${customer[0].lastName}"
        },
        {
          "title": "Phone number",
          "value": "${customer[0].phone}"
        }
      ]
    },
    ...
  ]
}

バインドするデータは JSON 文字列またはオブジェクトを指定します。

var template = new AdaptiveCardTemplate(File.ReadAllText("Template.json"));
var data = new
{
    Title = "Please confirm your order:",
    Customer = new[]
    {
        new
        {
            FirstName = "John",
            LastName = "Smith",
            Phone = "(555) 555-5555"
        }
    }
};
var card = template.expand(data);
Console.WriteLine(card);

動的に表示する内容を制御する

$when を使うことで、要素の表示の有無を制御できます。たとえば、先のテンプレートで電話番号が入力されていなければ非表示にするには、次のようにします。

  {
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
      {
        "type": "TextBlock",
        "text": "${title}",
        "wrap": true,
        "style": "heading"
      },
      {
        "type": "FactSet",
        "facts": [
          {
            "title": "Name",
            "value": "${customer[0].firstName} ${customer[0].lastName}"
          },
          {
            "title": "Phone number",
            "value": "${customer[0].phone}"
+           "$when": "${length(customer[0].phone) > 0}"
          }
        ]
      },
      ...
    ]
  }

アダプティブ カードでは以下の演算子が使用できます。

https://learn.microsoft.com/ja-jp/azure/bot-service/bot-builder-concept-adaptive-expressions?WT.mc_id=M365-MVP-5002941

今回は length 関数を使っていますが、そのほかにも組み込みの関数があります。

https://learn.microsoft.com/ja-jp/azure/bot-service/adaptive-expressions/adaptive-expressions-prebuilt-functions?WT.mc_id=M365-MVP-5002941

null の扱い

バインドされる値が null の場合、変換されずに式そのままが出力されます。これを防ぐには、空文字列など null 以外の値を設定することを強制するか、テンプレート式で対応する必要があります。

  {
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
      {
        "type": "TextBlock",
-       "text": "${title}",
+       "text": "${if(empty(title), 'No title', title)}",
        "wrap": true,
        "style": "heading"
      },
      {
        "type": "FactSet",
        "facts": [
          {
            "title": "Name",
            "value": "${customer[0].firstName} ${customer[0].lastName}"
          },
          {
            "title": "Phone number",
            "value": "${customer[0].phone}"
          }
        ]
      },
      ...
    ]
  }

おわりに

テンプレートは Power Automate からアダプティブ カードを作成する場合でも利用できるため、ぜひ活用してください。

Discussion