SDK per la creazione di modelli di schede adattive

  • Articolo

Gli SDK per la creazione di modelli di schede adattive consentono di popolare con facilità un modello di scheda con dati reali su qualsiasi piattaforma supportata.

Per una panoramica della creazione di modelli di schede adattive, leggi l'argomento specifico.

Importante

Modifiche importanti apportate alla versione finale candidata di maggio 2020

Abbiamo lavorato intensamente per il rilascio della creazione di modelli e abbiamo finalmente raggiunto l'obiettivo. Abbiamo dovuto apportare alcune piccole modifiche importanti, man mano che ci avvicinavamo alla data del rilascio.

Modifiche importanti della versione di maggio 2020

  1. La sintassi di binding è cambiata da {...} a ${...}.
    • Ad esempio, "text": "Hello {name}" diventa "text": "Hello ${name}"
  2. L'API JavaScript non contiene più un oggetto EvaluationContext. Passa semplicemente i dati alla funzione expand. Per informazioni dettagliate, vedi la pagina dell'SDK.
  3. L'API .NET è stata riprogettata in modo da corrispondere più strettamente all'API JavaScript. Per informazioni dettagliate, leggi di seguito.

JavaScript

La libreria adaptivecards-templating è disponibile in npm e tramite CDN. Per la documentazione completa, vedi il collegamento al pacchetto.

npm

npm install

npm install adaptivecards-templating

CDN

<script src="https://unpkg.com/adaptivecards-templating/dist/adaptivecards-templating.min.js"></script>

Utilizzo

Nell'esempio seguente si presuppone che tu abbia installato anche la libreria adaptivecards per eseguire il rendering della scheda.

Se non prevedi di eseguire il rendering della scheda, puoi rimuovere il codice relativo a parse e render.

import * as ACData from "adaptivecards-templating";
import * as AdaptiveCards from "adaptivecards";
 
// Define a template payload
var templatePayload = {
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "Hello ${name}!"
        }
    ]
};
 
// Create a Template instance from the template payload
var template = new ACData.Template(templatePayload);
 
// Expand the template with your `$root` data object.
// This binds it to the data and produces the final Adaptive Card payload
var cardPayload = template.expand({
   $root: {
      name: "Matt Hidinger"
   }
});
 
// OPTIONAL: Render the card (requires that the adaptivecards library be loaded)
var adaptiveCard = new AdaptiveCards.AdaptiveCard();
adaptiveCard.parse(cardPayload);
document.getElementById('exampleDiv').appendChild(adaptiveCard.render());

.NET

Nuget install

dotnet add package AdaptiveCards.Templating

Utilizzo

// Import the library 
using AdaptiveCards.Templating;

var templateJson = @"
{
    ""type"": ""AdaptiveCard"",
    ""version"": ""1.2"",
    ""body"": [
        {
            ""type"": ""TextBlock"",
            ""text"": ""Hello ${name}!""
        }
    ]
}";

// Create a Template instance from the template payload
AdaptiveCardTemplate template = new AdaptiveCardTemplate(templateJson);

// You can use any serializable object as your data
var myData = new
{
    Name = "Matt Hidinger"
};

// "Expand" the template - this generates the final Adaptive Card payload
string cardJson = template.Expand(myData);

Funzioni personalizzate

Le funzioni personalizzate possono essere aggiunte alla libreria di espressioni adattive, oltre alle funzioni predefinite.

Nell'esempio seguente viene aggiunta la funzione personalizzata stringFormat, usata per formattare una stringa.

string jsonTemplate = @"{
    ""type"": ""AdaptiveCard"",
    ""version"": ""1.0"",
    ""body"": [{
        ""type"": ""TextBlock"",
        ""text"": ""${stringFormat(strings.myName, person.firstName, person.lastName)}""
    }]
}";

string jsonData = @"{
    ""strings"": {
        ""myName"": ""My name is {0} {1}""
    },
    ""person"": {
        ""firstName"": ""Andrew"",
        ""lastName"": ""Leader""
    }
}";

AdaptiveCardTemplate template = new AdaptiveCardTemplate(jsonTemplate);

var context = new EvaluationContext
{
    Root = jsonData
};

// a custom function is added
AdaptiveExpressions.Expression.Functions.Add("stringFormat", (args) =>
{
    string formattedString = "";

    // argument is packed in sequential order as defined in the template
    // For example, suppose we have "${stringFormat(strings.myName, person.firstName, person.lastName)}"
    // args will have following entries
    // args[0]: strings.myName
    // args[1]: person.firstName
    // args[2]: strings.lastName
    if (args[0] != null && args[1] != null && args[2] != null) 
    {
        string formatString = args[0];
        string[] stringArguments = {args[1], args[2] };
        formattedString = string.Format(formatString, stringArguments);
    }
    return formattedString;
});

string cardJson = template.Expand(context);

Risoluzione dei problemi

D: Perché mi sono imbattuto in un'eccezione di tipo AdaptiveTemplateException con chiamata a expand()?
A. Se il messaggio di errore è simile a "<elemento> che causa l'errore" nella riga, "<numero> di riga" non è valido per '$data : ' pair".
Assicurarsi che il valore specificato per "$data" sia json valido, ad esempio number, boolean, object e array, oppure se segue la sintassi corretta per il linguaggio del modello adattivo e la voce esiste nel contesto dati in corrispondenza del numero di riga.

D: Perché mi sono imbattuto in un'eccezione di tipo ArgumentNullException con chiamata a expand()?
A. Se il messaggio di errore è simile a" Controllare se è impostato il contesto dati padre oppure immettere un valore non Null per "<elemento che causa un errore>" nella riga "<numero di> riga".
Indica che non esiste alcun contesto dati per il data binding richiesto. Verifica che il contesto dati radice sia impostato, se esistente, e che qualsiasi contesto dati sia disponibile per il binding corrente come indicato dal numero di riga.

D: Perché l'indicazione data/ora in formato RFC 3389, ad esempio "2017-02-14T06:08:00Z", se usata con un modello non funziona con le funzioni TIME/DATE?
A. Il pacchetto NuGet di .NET SDK versione 1.0.0-rc.0 presenta questo comportamento, che è stato corretto nelle versioni successive. Il comportamento predefinito del deserializzatore json.Net modifica la stringa del formato data/ora e viene disabilitato per le versioni successive. Usare la funzione formatDateTime() per formattare la stringa data/ora con RFC 3389 come illustrato in questo esempio. In alternativa, è possibile ignorare le funzioni TIME/DATE e usare semplicemente formatDateTime(). Per altre informazioni su formatDateTime(), visitare qui.