AsyncApi–Share your message contracts in a language agnostic manner–Part 2

Yesterday I introduced the AsyncApi specification as a way to share message contracts in a language neutral way. Let’s continue today by looking how we can generate a C# messagecontract based on your AsyncAPI specification file.

Here is the example specification file again that I shared yesterday:

	asyncapi: 2.3.0
	info:
	title: Mail Service
	version: 1.0.0
	description: This service is in charge of asynchronous mail sending
	channels:
	mailqueue:
	publish:
	message:
	$ref: '#/components/messages/SendMailCommand'
	subscribe:
	message:
	$ref: '#/components/messages/MailSentEvent'
	servers:
	development:
	url: development.example.be
	protocol: amqp
	description: Development RabbitMQ server
	acceptatie:
	url: acceptance.example.be
	protocol: amqp
	description: Acceptance RabbitMQ server
	components:
	messages:
	SendMailCommand:
	payload:
	type: object
	properties:
	subject:
	type: string
	format: string
	description: Subject of the email
	from:
	type: string
	format: email
	description: Emailaddress of the sender
	to:
	type: string
	format: email
	description: Emailaddress of the receiver
	body:
	type: string
	format: string
	description: Body of the email
	MailSentEvent:
	payload:
	type: object
	properties:
	subject:
	type: string
	format: string
	description: Subject of the email
	from:
	type: string
	format: email
	description: Emailaddress of the sender
	to:
	type: string
	format: email
	description: Emailaddress of the receiver

view raw message.yaml hosted with ❤ by GitHub

To transform this specification file to a data contract, we can use the Async API generator. The generator uses templates to specify what must be generated.

There is a list of official generator templates, unfortunately C# is not part of this list. Thanks to the community a csharp compatible template exists; https://github.com/jonaslagoni/asyncapi-quicktype-template

Let’s try that one!

Install the generator

First install the generator through NPM:

npm install -g @asyncapi/generator

You can optionally pre-install the quicktype template:

npm install -g @lagoni/asyncapi-quicktype-template

Generate C# Message contracts

Now we can generate the C# message contracts:

ag message.yaml @lagoni/asyncapi-quicktype-template -o output --param "quick
typeLanguage=csharp"

You can check the full list of available parameters for this template here: https://github.com/quicktype/quicktype/blob/e6cc44fdfcb75c3f3ed3e12f69f15a0c863a1a05/src/quicktype-core/language/CSharp.ts#L115

This will generate 2 message contracts:

	// <auto-generated />
	//
	// To parse this JSON data, add NuGet 'Newtonsoft.Json' then do:
	//
	// using MailSentEventNameSpace;
	//
	// var mailSentEvent = MailSentEvent.FromJson(jsonString);
	namespace MailSentEventNameSpace
	{
	using System;
	using System.Collections.Generic;
	using System.Globalization;
	using Newtonsoft.Json;
	using Newtonsoft.Json.Converters;
	public partial class MailSentEvent
	{
	/// <summary>
	/// Emailaddress of the sender
	/// </summary>
	[JsonProperty("from", NullValueHandling = NullValueHandling.Ignore)]
	public string From { get; set; }
	/// <summary>
	/// Subject of the email
	/// </summary>
	[JsonProperty("subject", NullValueHandling = NullValueHandling.Ignore)]
	public string Subject { get; set; }
	/// <summary>
	/// Emailaddress of the receiver
	/// </summary>
	[JsonProperty("to", NullValueHandling = NullValueHandling.Ignore)]
	public string To { get; set; }
	}
	public partial class MailSentEvent
	{
	public static MailSentEvent FromJson(string json) => JsonConvert.DeserializeObject<MailSentEvent>(json, MailSentEventNameSpace.Converter.Settings);
	}
	public static class Serialize
	{
	public static string ToJson(this MailSentEvent self) => JsonConvert.SerializeObject(self, MailSentEventNameSpace.Converter.Settings);
	}
	internal static class Converter
	{
	public static readonly JsonSerializerSettings Settings = new JsonSerializerSettings
	{
	MetadataPropertyHandling = MetadataPropertyHandling.Ignore,
	DateParseHandling = DateParseHandling.None,
	Converters =
	{
	new IsoDateTimeConverter { DateTimeStyles = DateTimeStyles.AssumeUniversal }
	},
	};
	}
	}

view raw MailSentEvent.cs hosted with ❤ by GitHub

	// <auto-generated />
	//
	// To parse this JSON data, add NuGet 'Newtonsoft.Json' then do:
	//
	// using SendMailCommandNameSpace;
	//
	// var sendMailCommand = SendMailCommand.FromJson(jsonString);
	namespace SendMailCommandNameSpace
	{
	using System;
	using System.Collections.Generic;
	using System.Globalization;
	using Newtonsoft.Json;
	using Newtonsoft.Json.Converters;
	public partial class SendMailCommand
	{
	/// <summary>
	/// Body of the email
	/// </summary>
	[JsonProperty("body", NullValueHandling = NullValueHandling.Ignore)]
	public string Body { get; set; }
	/// <summary>
	/// Emailaddress of the sender
	/// </summary>
	[JsonProperty("from", NullValueHandling = NullValueHandling.Ignore)]
	public string From { get; set; }
	/// <summary>
	/// Subject of the email
	/// </summary>
	[JsonProperty("subject", NullValueHandling = NullValueHandling.Ignore)]
	public string Subject { get; set; }
	/// <summary>
	/// Emailaddress of the receiver
	/// </summary>
	[JsonProperty("to", NullValueHandling = NullValueHandling.Ignore)]
	public string To { get; set; }
	}
	public partial class SendMailCommand
	{
	public static SendMailCommand FromJson(string json) => JsonConvert.DeserializeObject<SendMailCommand>(json, SendMailCommandNameSpace.Converter.Settings);
	}
	public static class Serialize
	{
	public static string ToJson(this SendMailCommand self) => JsonConvert.SerializeObject(self, SendMailCommandNameSpace.Converter.Settings);
	}
	internal static class Converter
	{
	public static readonly JsonSerializerSettings Settings = new JsonSerializerSettings
	{
	MetadataPropertyHandling = MetadataPropertyHandling.Ignore,
	DateParseHandling = DateParseHandling.None,
	Converters =
	{
	new IsoDateTimeConverter { DateTimeStyles = DateTimeStyles.AssumeUniversal }
	},
	};
	}
	}

view raw SendMailCommand.cs hosted with ❤ by GitHub

Generate documentation

The generator templates are quite versatile. So can you also use it to generate documentation in HTML or Markdown format.

ag message.yaml @asyncapi/html-template -o output

Here is how the generated html output looks like: