Vereniging-COIN.Sdk.BS 1.6.4

dotnet add package Vereniging-COIN.Sdk.BS --version 1.6.4                
NuGet\Install-Package Vereniging-COIN.Sdk.BS -Version 1.6.4                
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.
<PackageReference Include="Vereniging-COIN.Sdk.BS" Version="1.6.4" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Vereniging-COIN.Sdk.BS --version 1.6.4                
#r "nuget: Vereniging-COIN.Sdk.BS, 1.6.4"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Vereniging-COIN.Sdk.BS as a Cake Addin
#addin nuget:?package=Vereniging-COIN.Sdk.BS&version=1.6.4

// Install Vereniging-COIN.Sdk.BS as a Cake Tool
#tool nuget:?package=Vereniging-COIN.Sdk.BS&version=1.6.4                

.NET Bundle Switching SDK

Introduction

This SDK supports secured access to the bundle switching API.

For a quick start, follow the steps below:

Setup

Sample Project for the Bundle Switching API

A sample project is provided in the bundle-switching-sdk-samples directory.

NuGet Package

This SDK is published as the NuGet package 'Vereniging-COIN.Sdk.BS'.

Configure Credentials

For secure access credentials are required.

  • Check this README to find out how to configure these.
  • In summary you will need:
    • a consumer name
    • a private key file (or a System.Security.Cryptography.RSA instance containing this key)
    • a file containing the encrypted Hmac secret (or a System.Security.Cryptography.HMACSHA256 instance containing this (decrypted) secret)
  • These can be used to create instances of the BundleSwitchingService and the SseConsumer, which is needed for the BundleSwitchingMessageConsumer.

Messages

BsMessage.cs shows how the bundle switching domain has been structured. The interfaces from this file can be used to define methods that can accept any message. Coin.Sdk.BS.Messages.V5.Utils contains the useful static methods TypeName and Deserialize.

Send Messages

The BundleSwitchingService has a SendMessage method to send any bundle switching message - wrapped in an instance of the MessageEnvelope class - to the API.

Consume Messages

Create Message Listener

For message consumption, the bundle switching API makes use of HTTP's ServerSentEvents. The SDK offers a Listener interface IBundleSwitchingMessageListener which is triggered upon reception of a message payload. Whenever the API doesn't send any other message for 20 seconds, it sends an empty 'heartbeat' message, which triggers the OnKeepAlive() method.

Start consuming messages

The BundleSwitchingMessageConsumer has three startConsuming...() methods for consuming messages, of which startConsumingUnconfirmed() is most useful. All these methods need an instance of the IBundleSwitchingMessageListener.

Consume specific messages using filters

The BundleSwitchingMessageConsumer provides various filters for message consumption. The filters are:

  • MessageType: All possible message types, including errors. Use the MessageType-enumeration to indicate which messages have to be consumed.
  • confirmation status: By using startConsumingAll(), all messages will be received, both confirmed and unconfirmed.
    Note: this enables the consumption of the whole message history. Therefore, this requires you to supply an implementation of the IOffsetPersister interface. The purpose of this interface is to track the message-id of the last received and processed message. In the case of a reconnect, message consumption will then resume where it left off.
  • offset: starts consuming messages based on the given message-id offset. Note: it is the responsibility of the client to keep track of the offset.
Confirm Messages

Once a consumed message has been processed it needs to be confirmed. To confirm a message use the BundleSwitchingService.sendConfirmation(id) method.

Error Handling

The bundle switching API can return errors in one of two ways:

  1. The server received an incorrect payload and replies with an error response (synchronous)

    The REST layer of the system only performs basic payload checks, such as swagger schema validity and message authorization. Any errors in these checks are immediately returned as an error reply. The BundleSwitchingService.SendMessage method returns these as ErrorResponse. Other http errors are thrown as HttpListenerException.

  2. As a ServerSentEvent containing an ErrorFoundMessage (asynchronous)

    The system performs detailed functional validation asynchronously. Errors in this stage are sent via a ServerSentEvent.

    Note: ErrorFound messages need to be confirmed like any other message received via a ServerSentEvent.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
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.