MsTeams.TemplateEngine 1.0.0

.NET Standard 2.0
There is a newer version of this package available.
See the version list below for details.
NuGet\Install-Package MsTeams.TemplateEngine -Version 1.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
dotnet add package MsTeams.TemplateEngine --version 1.0.0
<PackageReference Include="MsTeams.TemplateEngine" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add MsTeams.TemplateEngine --version 1.0.0
#r "nuget: MsTeams.TemplateEngine, 1.0.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install MsTeams.TemplateEngine as a Cake Addin
#addin nuget:?package=MsTeams.TemplateEngine&version=1.0.0

// Install MsTeams.TemplateEngine as a Cake Tool
#tool nuget:?package=MsTeams.TemplateEngine&version=1.0.0

MsTeams Template Engine

This project use Scriban to create a template engine for AdaptiveCards

Why

Using adaptive cards website we can have a json with data binding. A non technical person can create a complex adaptive card using only WYSIWYG !! But a technical person need to integrate this JSON inside an application. To do so you need an engine that can parse and interpret the json to send it using the bot framework.

Microsoft already provide a template engine but it does not have the following requirements :

  • Include other templates in one template (usefull to separate your template in small parts)
  • I18n function : We don't want to have a template per language, so we must have a way to translate part of the template
  • JSON helpers : To have a reliable way of adding variable inside the json they must be encoded using json helpers

Installation

Add-Package MsTeams.TemplatingEngine
Add-Package Microsoft.Extensions.Localization

In Startup.cs add in ConfigureServices

services.AddMsTeamsTemplateEngine()
services.AddLocalization()

How to parse and render a template

public class ProductController
{
	readonly AdaptiveCardTemplateEngine engine;

	public ProductController(AdaptiveCardTemplateEngine engine)
	{
		this.engine = engine;
	}

	public void Show()
	{
		var template = engine.ParseFile("Product/show.tjson");
		var card = engine.RenderToAdaptiveCard(template, new { id = 5, title = "Chorizo", price = 5.99 });
		// Send card to MsTeams using Bot Framework
	}
}

The template language

The document syntax is available on Scriban page

Include

You can include a template in a template.

Simple case

Folder structure

.
├── main.tjson
└── myinclude.tjson

Include syntax

include 'myinclude.tjson'

Extension is not mandatory, if not provided it will use the includer extension

include 'myinclude'
Shared case

The template loader will look in a folder call Shared if the template is not algonside the current template.

Folder structure

.
├── main.tjson
└── Shared/
    └── myinclude.tjson

Include syntax

include 'myinclude'

Also it will look in descendent folder for a Shared containing your template

Folder structure

.
├── Views/
│   └── Product/
│       └── main.tjson
└── Shared/
    └── myinclude.tjson

Include syntax

include 'myinclude'

JSON Encoding

To encode a value to json you must use the json function

Example
Simple object
var result = engine.Render(template, new { label = "LabelContent" });

Template :

{
	"label": {{ json label }}
}

Output :

{
	"label": "LabelContent"
}
Complex object
var result = engine.Render(template, new { data = new { label = "LabelContent" } });

Template :

{
	"content": {{ json data }}
}

Output :

{
	"content": {
		"label": "LabelContent"
	}
}

i18n Function

We use the .Net Localization mechanism IStringLocalizer and IStringLocalizerFactory. To get a localized string, you must first declare at the assembly from where the resx will be loaded using tAssembly 'AssemblyName'. And then you can get a translated string by using the t function : t 'TranslateKeyInResx'

{{ tAssembly 'MsTeamsTemplatingEngine.Tests' }}
{
	"label": "{{ t 'TestKey' }}"
}

See LocalizeTests for full example

Invoke action helpers

This is tightly linked to Whyse routing system for MsTeams action. When using adaptive cards you can get the full data payload for an invoke submit action using the invokeSubmitData function.

Code :

var result = engine.Render(template, new { productData = new { productId = 5 } });

Template :

{
	"type": "ActionSet",
	"actions": [
		{
			"title": "Buy Product",
			"type": "Action.Submit",
			"style": "positive",
			"id": "send",
			{{ invokeSubmitData '/product/buy' productData }}
		}
	]
}

Output

{
	"type": "ActionSet",
	"actions": [
		{
			"title": "Buy Product",
			"type": "Action.Submit",
			"style": "positive",
			"id": "send",
			"data": {
				"msteams": {
					"type": "invoke",
					"value": {
						"action": "/product/buy",
						"productId": 5
					}
				}
			}
		}
	]
}
Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.1 1,966 6/8/2020
1.0.0 306 6/3/2020