Bindings

Overview

Bindings exists in their own package.

Writing

Writing is exceedingly simply for bindings. Simply reference the binding and write. There is no need to do anything special Say we have the following (Example for the Pulsar ServerBinding)

var doc = new AsyncApiDocument();
doc.Info = new AsyncApiInfo()
{
    Description = "test description",
};
doc.Servers.Add("production", new AsyncApiServer
{
    Description = "test description",
    Protocol = "pulsar+ssl",
    Url = "example.com",
    Bindings = new AsyncApiBindings<IServerBinding>()
    {
        new PulsarServerBinding()
        {
            Tenant = "Staging",
        }
    },
});

var yaml = doc.SerializeAsYaml(AsyncApiVersion.AsyncApi2_0);

Yields the following yaml output

asyncapi: '2.6.0'
info:
  description: test description
servers:
  production:
    url: example.com
    protocol: pulsar+ssl
    description: test description
    bindings:
      pulsar:
        tenant: Staging

Reading

Say we want to read the yaml from before

asyncapi: '2.6.0'
info:
  description: test description
servers:
  production:
    url: example.com
    protocol: pulsar+ssl
    description: test description
    bindings:
      pulsar:
        tenant: Staging

We need to specifically add binding-support to the reader, through AsyncApiReaderSettings Note there are some nifty helpers in the BindingsCollection class, that helps add collections of bindings (or All), but individual bindings can also be added.

var settings = new AsyncApiReaderSettings();
settings.Bindings = BindingsCollection.Pulsar; // Pulsar Server and Channel bindings
var reader = new AsyncApiStringReader(settings);
var deserialized = reader.Read(yaml, out var diagnostic);

The above will deserialize the binding correctly.

Custom Bindings

There are 4 types of bindings and thus 4 abstract classes that can be implemented;

1. ServerBinding<T>
2. ChannelBinding<T>
3. OperationBinding<T>
4. MessageBinding<T>

T must be the same type as the class that implements it.

The steps to create a custom binding

1. Reference the bindings package through NuGet.
2. Create your binding (in your own codebase)

public class FooBinding : ChannelBinding<FooBinding>
{
    public string Foo { get; set; }
    public string Bar { get; set; }

    public override string BindingKey => "foo";

    protected override FixedFieldMap<FooBinding> FixedFieldMap => new FixedFieldMap<FooBinding>()
    {
        { "bindingVersion", (a, n) => { a.BindingVersion = n.GetScalarValue(); } },
        { "foo", (a, n) => { a.Foo = n.GetScalarValue(); } },
        { "bar", (a, n) => { a.Bar = n.GetScalarValue(); } },
    };

    public override void SerializeProperties(IAsyncApiWriter writer)
    {
        writer.WriteStartObject();
        writer.WriteRequiredProperty("foo", this.Foo);
        writer.WriteRequiredProperty("bar", this.Bar);
        writer.WriteOptionalProperty(AsyncApiConstants.BindingVersion, this.BindingVersion);
        writer.WriteExtensions(this.Extensions);
        writer.WriteEndObject();
    }
}

3. Follow the same steps as in Reading or Writing above. Note. For Writing; you must explicitly add the custom bindings to the ReaderSettings.