.NET SDK, v3.0
SDK libraries to reference:
Fifa.ConnectServiceBus.Sdk.dll
Microsoft.Rest.ClientRuntime.dll
Newtonsoft.Json.dll
Microsoft.IdentityModel.Clients.ActiveDirectory
Microsoft.IdentityModel.Clients.ActiveDirectory.Platform
The entry point of the SDK is FifaConnectServiceBusClient
. With a single instance of this class all the requests can be made. In order to authenticate to the service you have to provide a set of client credentials.
In order to create a new instance of the client, instance of IPrivateKeyStorage
must be provided. By default SDK uses PrivateKeyMemoryStorage
class that implements mentioned interface. Next step is to provide instance(s) of X509Certificate2
into such container. Each certificate consists of the key (from generated file) and password (optionally). Please take a look at the following example:
var environment = ConnectServiceBusEnvironment.Beta;
var credentials = new ClientCredentials("clientId", "secretKey");
var certificate = new X509Certificate2();
certificate.Import(TestResources.cert_pfx, "Testing123", X509KeyStorageFlags.DefaultKeySet);
var privateStore = new PrivateKeyMemoryStorage(certificate);
In order to generate a new certificate follow instructions from fifa-connectservicebus-certificates-generation.html
. When a new pair of certificates (public and private) is generated and a new public certificate is uploaded, then it's required to update collection of private certificates returned by implementation of IPrivateKeyStorage
. Since some messages could be encrypted before new public certificate was uploaded, implementation of IPrivateKeyStorage must return current and previous private certificate to ensure that all messages can be decrypted.
Correct order of steps is the following:
IPrivateKeyStorage
returns old and new private certificatesPlease take a look at the following example, where two certificates are used by IPrivateKeyStorage
:
var environment = ConnectServiceBusEnvironment.Beta;
var credentials = new ClientCredentials("clientId", "secretKey");
var certificate = new X509Certificate2();
certificate.Import(TestResources.cert_pfx, "Testing123", X509KeyStorageFlags.DefaultKeySet);
var oldCertificate = new X509Certificate2();
oldCertificate.Import(TestResources.old_cert_pfx, "Testing123", X509KeyStorageFlags.DefaultKeySet);
var privateStore = new PrivateKeyMemoryStorage(certificate, oldCertificate);
var environment = ConnectServiceBusEnvironment.Beta;
var credentials = new ClientCredentials("clientId", "secretKey");
var client = new FifaConnectServiceBusClient(environment, credentials, privateStore);
where environment is an instance of type ConnectServiceBusEnvironment
. It provides information about the service to make request to.
By default, the above constructor uses a NullLogger
, which does nothing. However, to use logging, provide your own implementation of ILogger
.
var environment = ConnectServiceBusEnvironment.Beta;
var credentials = new ClientCredentials("clientId", "secretKey");
var logger = new YourOwnLogger();
var client = new FifaConnectServiceBusClient(environment, credentials, privateStore, logger);;
In case of need for upload or download certificate, you have to use an instance of FifaConnectServiceBusCertificateClient
.
var environment = ConnectServiceBusEnvironment.Beta;
var credentials = new ClientCredentials("clientId", "secretKey");
var certificateClient = new FifaConnectServiceBusCertificateClient(environment, credentials);
Encryption can be disabled using setUseEncryption()
method from FifaConnectServiceBusClient
instance.
var environment = ConnectServiceBusEnvironment.Beta;
var credentials = new ClientCredentials("clientId", "secretKey");
var client = new FifaConnectServiceBusClient(environment, credentials, new NullPrivateKeyProvider());
client.UseEncryption = false;
Recipient of the message is specified by the recipient
parameter. It's actually a name of a queue that acts as an inbox for other client (e.g. registration system in a different MA).
In order to send a message in FIFA Connect Service Bus service, provide content
as byte[]
. A recipient
needs to be provided as well.
By convention value of the recipient
is the FIFA ID of the receiving organisation. However, for certain applications it may have format of FIFAID_application
. In case of any doubts, please contact FIFA Connect Service Bus Support team to get proper value of recipient
.
Example:
try
{
await client.Send(recipient, content);
}
catch (InvalidClientDataException ex)
{
// data sent to the service was invalid
var details = ex.BadRequestResponse;
}
catch (AuthenticationException ex)
{
// invalid client credentials
}
catch (UnauthorizedException ex)
{
// unauthorized
}
catch (PublicCertificateNotFoundException ex)
{
// there is no public certificate for given queue
}
catch (CryptographyException ex)
{
// exception when encrypting content
}
catch (QueueNotFoundException ex)
{
// there is no queue for specified recipient
}
catch (FifaConnectServiceBusException ex)
{
// some other error occurred, see the details
var response = ex.HttpOperationResponse;
}
To send additional meta data of the message use overloaded send method:
var action = "/person/getDetails";
var properties = new Dictionary<string, string>();
properties.Add("id", "BVGE8T6");
await client.Send(recipient, content, action, properties);
Please note that the method is not transactional. Message is immediately removed from the queue. For transactional message processing use PeekLock
method.
The timeout
parameter can be specified. In Connect Service Bus context timeout
defines how long a request waits before returning that there is no message in the queue. When no message is found, FifaConnectServiceBusClient
will return null
.
try
{
var message = await client.Receive().ConfigureAwait(false);
}
catch (InvalidClientDataException ex)
{
// data sent to the service was invalid
var details = ex.BadRequestResponse;
}
catch (AuthenticationException ex)
{
// invalid client credentials
}
catch (UnauthorizedException ex)
{
// unauthorized
}
catch (CryptographyException ex)
{
// exception when encrypting content
}
catch (QueueNotFoundException ex)
{
// there is no queue for specified recipient
}
catch (FifaConnectServiceBusException ex)
{
// some other error occurred, see the details
var response = ex.HttpOperationResponse;
}
In order to receive a message from Connect Service Bus and leave it in the queue use PeekLock
method. Received message will not be visible for other Connect Service Bus clients for 120 seconds. During that time period actions like Delete
, Unlock
or RenewLock
can be triggered. If none of the above actions is taken, message will be returned to the queue.
In the Message
some metadata can be found in property BrokerProperties
. The most important are MessageId
and LockToken
that are used as required parameters in methods Delete
, Unlock
or RenewLock
. In addition above properites can be found in instance of Message
class.
try
{
var message = client.PeekLock();
}
catch (InvalidClientDataException ex)
{
// data sent to the service was invalid
var details = ex.BadRequestResponse;
}
catch (AuthenticationException ex)
{
// invalid client credentials
}
catch (UnauthorizedException ex)
{
// unauthorized
}
catch (CryptographyException ex)
{
// exception when encrypting content
}
catch (QueueNotFoundException ex)
{
// there is no queue for specified recipient
}
catch (FifaConnectServiceBusException ex)
{
// some other error occurred, see the details
var response = ex.HttpOperationResponse;
}
Method used to delete a locked message.
try
{
await client.Delete(message.Id, message.LockToken);
}
catch (InvalidClientDataException ex)
{
// data sent to the service was invalid
var details = ex.BadRequestResponse;
}
catch (AuthenticationException ex)
{
// invalid client credentials
}
catch (UnauthorizedException ex)
{
// unauthorized
}
catch (FifaConnectServiceBusException ex)
{
// some other error occurred, see the details
var response = ex.HttpOperationResponse;
}
Message can be returned to the queue using Unlock
method.
try
{
await client.Unlock(message.Id, message.LockToken);
}
catch (InvalidClientDataException ex)
{
// data sent to the service was invalid
var details = ex.BadRequestResponse;
}
catch (AuthenticationException ex)
{
// invalid client credentials
}
catch (UnauthorizedException ex)
{
// unauthorized
}
catch (FifaConnectServiceBusException ex)
{
// some other error occurred, see the details
var response = ex.HttpOperationResponse;
}
Lock can be renewed for the next 120 seconds.
try
{
await client.RenewLock(message.Id, message.LockToken);
}
catch (InvalidClientDataException ex)
{
// data sent to the service was invalid
var details = ex.BadRequestResponse;
}
catch (AuthenticationException ex)
{
// invalid client credentials
}
catch (UnauthorizedException ex)
{
// unauthorized
}
catch (FifaConnectServiceBusException ex)
{
// some other error occurred, see the details
var response = ex.HttpOperationResponse;
}
Recommended way to upload a public certificate is the upload using console application located in certificate-upload-console
folder. For more information please refer to Certificate Generation documentation. If console application can't be used, use UploadCertificate
method instead. Take a look at the following example:
var certificateData = File.ReadAllBytes(certificateFilePath); // certificateFilePath: path to public_cert.pem file
try
{
await client.UploadCertificate(certificateData);
}
catch (InvalidClientDataException ex)
{
// data sent to the service was invalid
var details = ex.BadRequestResponse;
}
catch (AuthenticationException ex)
{
// invalid client credentials
}
catch (UnauthorizedException ex)
{
// unauthorized
}
catch (FifaConnectServiceBusException ex)
{
// some other error occurred, see the details
var response = ex.HttpOperationResponse;
}
To download public certificate for specific organisation use DownloadCertificate
method. Please take a look at the following example:
try
{
var certificateRawData = await client.DownloadCertificate(queueIdentifier).ConfigureAwait(false);
}
catch (InvalidClientDataException ex)
{
// data sent to the service was invalid
var details = ex.BadRequestResponse;
}
catch (AuthenticationException ex)
{
// invalid client credentials
}
catch (UnauthorizedException ex)
{
// unauthorized
}
catch (DataNotFoundException ex)
{
// certificate has not been found
}
catch (FifaConnectServiceBusException ex)
{
// some other error occurred, see the details
var response = ex.HttpOperationResponse;
}
Currently each recipient's queue has a quota of 80 GB (both content and message headers size is counted). When queue reaches its limit, new messages cannot be send to the recipient, so senders get an error from Service Bus API and SDK.
Each queue stores messages for 7 days. If message is not received by the recipient messages, it is moved to dead-letter queue and support team receives notification about unprocessed message. On client request support team can move a message to primary queue so that it can be received and processed by an application. Alternatively message can be permanently deleted from a dead-letter queue.
If client using Connect Service Bus SDK downloads message but fails to process it correctly (i.e. handler throws an exception), the counter of failed delivery is increased. If delivery fails 10 times, message is moved to a dead-letter queue. Depending on the reason different actions can be taken:
Maximum message size is 10MB. If this limit is exceeded then Connect Service Bus will return 400 (Bad Request) response code. As a result InvalidClientDataException
will be thrown.
Any instance members are not guaranteed to be thread safe. In particular all methods on FifaConnectServiceBusClient
cannot be called from multiple threads simultaneously. If needed, new instance of FifaConnectServiceBusClient
should be created per thread.
The following changes were introduced in version 3.0 of the SDK when comparing to version 2.1: