// Create a new BusAccess, with default connection settings and default authentication provider, and connect to the bus immediately.
using (var bus = new BusAccess())
{
    // ...
}

// OR

// Create a new BusAccess, with an authentication provider, and connect to the bus immediately.
using (var bus = new BusAccess(new ClientAuthentication("620f8ca6-0b0e-11e6-b512-3e1d05defe78", "19928139-f7da-4e90-b551-ad6bdaa8d9ab"))) {
{
    // ...
}

// Create a new BusAccess, with non-default connection settings and default authentication provider, and connect to the bus immediately.
using (var bus = new BusAccess((new ConnectionInfo { InitialAttempts = 5 }))) {
{
    // ...
}

// OR

// Create a new BusAccess, with non-default connection settings and an authentication provider, and connect to the bus immediately.
using (var bus = new BusAccess((new ConnectionInfo { InitialAttempts = 5, AuthenticationProvider = new ClientAuthentication("620f8ca6-0b0e-11e6-b512-3e1d05defe78", "19928139-f7da-4e90-b551-ad6bdaa8d9ab") }))) {
{
    // ...
}

    CancellationTokenSource cancel = new CancellationTokenSource();

// ...

    var bus = new BusAccess(new IpAuthenticationProvider(), service, false));

// ...

    try
    {
        bus.Connect(cancel.Token);
    }
    catch(OperationCanceledException)
    {
        // Connect was canceled
    }

static void Main()
{
#if (DEBUG)
    Environment.SetEnvironmentVariable("ACS_BUS_QUERY_TIMEOUT", "-1");
    Environment.SetEnvironmentVariable("ACS_GATEWAY_CONNECTION_LOST_THRESHOLD", "-1");
#endif

    // ...
}

namespace Avid.Platform.Bus
{
    public interface IConnectionSubscriber
    {
        void OnConnect();
        void OnDisconnect();
    }
}

// ...
public class CalculatorService : StandaloneService, IChannelMessageSubscriber, IConnectionSubscriber
{
    // ...
}

static void Main()
{
    var service = new CalculatorService();
    using (var bus = new BusAccess(new ConnectionInfo { Timeout = 2000, AuthenticationProvider = new ClientAuthentication("620f8ca6-0b0e-11e6-b512-3e1d05defe78", "19928139-f7da-4e90-b551-ad6bdaa8d9ab") }, service))
    {
        // ...
    }
}

    var msg = new Message("avid.acs.calculator", "global.test", 3, "echo");
    bus.Query(msg, new AnonAsyncQueryResult() {
        onSuccess = (Message result) => {
            if (result.HasErrors) {
                // ...
                return;
            }
            Console.WriteLine("Echo reply: " + result + ".");
        },
        onError = (OperationError error) => {
            Console.WriteLine("Failed to query service: " +  msg.ServiceType + ", error: " + error.Message + ".");
        },
        onTimeout = () => {
            Console.WriteLine("Timed-out querying service: " + msg.ServiceType + ".");
        }
    });
// ...

// ...
var request = new Message("registry", "global", 0, "updateServiceStatus");
request.Parameters.Add("status", "ok");
bus.Send(request, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to send message to service: " + request.ServiceType + ", error: " + error.Message + ".");
    }
});

// ...
var request = new Message("widget.factory", "global", 0, "makeLotsAndLotsOfWidgets");
bus.Broadcast(request, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to broadcast message to all service instance(s): " + request.ServiceType + ", error: " + error.Message + ".");
    }
});

// ...
var msg = new Message("avid.acs.calculator", "global.test", 3, "add");
msg.Parameters.Add("num1", 2);
msg.Parameters.Add("num2", 2);

bus.Zone("5b2123f1-3f8e-4fcb-9263-f7b98bbdab0c").Query(msg, new AnonAsyncQueryResult() {
    onSuccess = (Message result) => {
        int sum = result.Results.GetItem<int>("sum");
        Console.WriteLine("Sum = " + sum + ".");
    },
    onError = (OperationError error) => {
        Console.WriteLine("Failed to query service: " + msg.ServiceType + ", error: " + error.Message + ".");
    },
    onTimeout = () => {
        Console.WriteLine("Timed-out querying service: " + msg.ServiceType + ".");
    }
});

// ...
var request = new Message("example.service", "global", 0, "doSomething");
bus.Zone("5b2123f1-3f8e-4fcb-9263-f7b98bbdab0c").Query(request, /* ... */);
bus.Zone("5b2123f1-3f8e-4fcb-9263-f7b98bbdab0c").Send(request, /* ... */);
bus.Zone("5b2123f1-3f8e-4fcb-9263-f7b98bbdab0c").Broadcast(request, /* ... */);

var request = new Message("example.service", "global", 1, "doSomething");
bus.MultiZone.Query(request, /* ... */);
bus.MultiZone.Send(request, /* ... */);
bus.MultiZone.Broadcast(request, /* ... */);
````

Note that `bus.MultiZone.Query` and `bus.MultiZone.Send` only send to one service instance in one zone.  If there is a service instance in the local zone, it sends to that one.  Otherwise it sends to a service instance in a remote zone (if one is available and registered with the `multi-zone` scope).  This is particularly useful if you know the service is in a zone, but aren't sure which one.

`bus.MultiZone.Broadcast` broadcasts to _all_ matching service instances in _all_ zones.

### Local Zone Communications

Note that there is also a `bus.LocalZone` object.  Invoking `Query`, `Send`, and `Broadcast` on this object is functionally equivalent to invoking the same methods on the base `bus` object.

## Wildcards Usage in the Realm

If multiple realms of the same service are registered, you can use wildcards to address any service instance satisfying a wildcard expression. Wildcards can substitute for any letters/digits between the dot delimiters.

For example, consider an Avid Platform service registered with the following realms:

    montreal.workgroup1;
    montreal.workgroup2;
    montreal.workgroup1.id1;
    montreal.workgroup1.id2;
    montreal.workgroup2.id1;
    montreal.workgroup2.id2;

In the above case, you can address the services by supplying the following wildcarded realms in the request:

    request = new Message("example.service", "*.*", 0, "echo");
    request = new Message("example.service", "*.*.*", 0, "echo");
    request = new Message("example.service", "montreal.*", 0, "echo");
    request = new Message("example.service", "montreal.workgroup1.id*", 0, "echo");
    request = new Message("example.service", "montreal.workgroup*.id2", 0, "echo");
    request = new Message("example.service", "montreal.*group*.id2", 0, "echo");

    // etc...

In contrast, the following wildcarded realms won't match any instance in the above example:

    *
    *.*.*.*
    montreal.workgroup*.id3

    // etc...

# Proxy Clients
After migration to .NET Core 2.0 Proxy Clients are not supported anymore. The feature will be reconsidered and reimplemented in future releases.

# Using the Avid Connector API to Host Services

You can use the Avid Connector API to host .NET services on the Avid Platform.

## Simple Services

The easiest way to host a service on the Avid Platform is to derive an object from `StandaloneService` and annotate it with the `Service` attribute. To expose a method in your class as an operation available on the Avid Platform, annotate the method with the `Operation` attribute, as illustrated in the following example:

**Note:** In versions of the API less than 2.5, the `IResponder` interface was used to respond to operations (rather than `IOperationContext`).

```c#
[Service("avid.platform.bus.examples.service.calculator", 1, "Performs simple arithmetic.", new int[] { 0 })]
[Examples("com.widget.Resources.Examples")]
[Error("DIVIDE_BY_ZERO", 400, ErrorSeverity.Error, "Division by zero, %{num1} and %{num2}.")]
class CalculatorService : StandaloneService
{
    [Operation("add", "Returns the sum of two numbers.")]
    [RestRequest("calculator/add")]
    [return: Result("sum")]
    public void Add(int a, int b, IOperationContext<int> responder)
    {
        responder.Respond(a + b);
    }

    [Operation("subtract", "Returns the difference of two numbers.")]
    [RestRequest("calculator/subtract")]
    [return: Result("difference")]
    public void Subtract(int a, int b, IOperationContext<int> responder)
    {
        responder.Respond( a - b);
    }

    [Operation("multiply", "Returns the product of two numbers.")]
    [RestRequest("calculator/multiply")]
    [return: Result("product")]
    public void Multiply(int a, int b, IOperationContext<int> responder)
    {
        responder.Respond( a * b);
    }

    [Operation("divide", "Returns the quotient of two numbers.")]
    [RestRequest("calculator/divide")]
    [return: Result("quotient")]
    public void Divide(int a, int b, IOperationContext<int> responder)
    {
        if (b == 0) {
            responder.Error(new Error("DIVIDE_BY_ZERO", new Dictionary<string, string> { { "num1", a.ToString() }, { "num2", b.ToString() } }));
            return;
        }
        responder.Respond( a / b);
    }
}

static void Main()
{
    var service = new CalculatorService();
    using (var bus = new BusAccess(new ConnectionInfo { Timeout = -1 }, service))
    {
        // Create and register a calculator service (asynchronously):
        bus.RegisterService(service,
            new ServiceOptions { RequestServiceConfiguration = false },
            new AnonAsyncOpResult<Avid.Platform.Bus.Service.ServiceBase>() {
                onSuccess = (Avid.Platform.Bus.Service.ServiceBase result) => {
                    eventLog.WriteEntry("Registered service: " + result + ".");
                },
                onError = (OperationError error) => {
                    eventLog.WriteEntry("Failed to register service: " + service + ", error: " +  error.Message + ".");
                    ExitCode = 3;
                }
            });

        // Process messages
        service.WaitForStop();
    }
}

namespace Avid.Platform.Bus.Service
{
    [Examples("Avid.Platform.Bus.Resources.CommonOperations")]
    public class ServiceBase : MarshalByRefObject
    {
        protected ServiceBase();
        protected ServiceBase(string realm);

        public IBusAccess Bus { get; internal set; }
        public IDataSet Config { get; }
        public ServiceInfo Info { get; }
        public ServiceStatus Status { get; set; }

        public virtual ServiceStatus OnRegistered();
        public virtual void OnServiceConfiguration(ServiceConfigurationEventArg configArg);
        public virtual void OnUnregistered();

        public override string ToString();
    }
}

public ErrorAttribute(string code, int status, ErrorSeverity severity, string messageTemplate, string description);

[Service("avid.platform.bus.examples.service.calculator", 1, "Performs simple arithmetic.", new int[] { 0 } )]
[Error("ADDITION_OVERFLOW", 500, ErrorSeverity.Error, "Addition overflow %{num1} and %{num2}.")]
[Error("DIVIDE_BY_ZERO", 400, ErrorSeverity.Error, "Division by zero, %{num1} and %{num2}.")]
public class ExampleCalculatorService : StandaloneService
{
    // ...
    [Operation("divide", "Returns the quotient of two numbers.")]
    [RestRequest("calculator/divide")]
    [return: Result("quotient")]
    public void Divide(int a, int b, IOperationContext<int> responder)
    {
        if (b == 0) {
            responder.Error(new Error("DIVIDE_BY_ZERO", new Dictionary<string, string> { { "num1", a.ToString() }, { "num2", b.ToString() } }));
            return;
        }
        responder.Respond( a / b);
    }

    // ...
}

using Avid.Platform.Bus.Exceptions;

public class OverflowException : Exception 
{
	public OverflowException(String code, long num1, long num2)
		: base("Addition overflow")
	{
		Data.Add(ExceptionKeys.ErrorCode, "ADDITION_OVERFLOW");
		Data.Add(ExceptionKeys.ErrorParameters, new Dictionary<string, string> { { "num1", num1.ToString() }, { "num2", num2.ToString() } });
	}
}
// ...

public void Add(int num1, int num2, IOperationContext<int> responder)
{
	if (AdditionWillOverflow(num1, num2))
		throw new OverflowException("ADDITION_OVERFLOW", num1, num2);
	responder.Respond(num1 + num2);
}

bus.MultiZone.RegisterService(new CalculatorService(), new AnonAsyncOpResult() {
            onSuccess = () => {
                Console.WriteLine("Register service succeeded.");
            },
            onError = (OperationError error) => {
                Console.WriteLine("Failed to register service, error: " + error.Message + ".");
            }
        });

public class Person
{
    public String FirstName { set; get; }
    public String LastName { set; get; }
}

// ...

[Operation("echoPersonInMessage", "Echo's back passed person.")]
[RestRequest("echoer/echoPersonInMessage")]
[return: Result("person")]
public void EchoPersonInMessage(Person person, IOperationContext<Message> responder)
{
    var response = new Message(this, "echoPersonInMessage");
    response.Results.Add("person", person);
    responder.Respond(response);
}

public override void OnServiceConfiguration(ServiceConfigurationEventArg configArg)
{
    ServiceStatus status = ServiceStatus.Suspended;
    try {
        var config = configArg.Configuration;
        //  ...

        status = ServiceStatus.Ok;
    } catch (BusAccessException ex) {
        Console.WriteLine("Failed to fetch service configuration, error: " + ex.Message + ".");
    } catch (Exception ex) {
        Console.WriteLine("Failed to process service configuration, error: " + ex.Message + ".");
    } finally {
        SetStatus(status, new AnonAsyncOpResult() {
            onError = (OperationError error) => {
                Console.WriteLine("Failed to set service status, error: " + error.Message + ".");
                Stop();
            }
        });
    }
}

transcodeService.SetStatus(ServiceStatus.Offline, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to set status, error: " + error.Message + ".");
    }
});

// ...

transcodeService.SetStatus(ServiceStatus.Ok, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to set status, error: " + error.Message + ".");
    }
});

[HealthCheck]
internal void serviceHealth(IHealthCheckReporter<CustomHealthInfo> healthCheckReporter)
{
     var info = new CustomHealthInfo("some text", true);
     healthCheckReporter.Report(HealthStatus.Ok, info);
 }

 [DataContract]
 public sealed class CustomHealthInfo {
     [DataMember(Name = "str")]
     public string Str {
         get; private set;
     }

     [DataMember(Name = "flag")]
     public bool Flag {
         get; private set;
     }

     [JsonConstructor]
     internal CustomHealthInfo(String str, bool flag)
     {
         Str = str;
         Flag = flag;
     }
 }

[Service("avid.platform.bus.examples.service.calculator", 3, "Performs simple arithmetic.", new int[] { 2, 1 })]
[Examples("com.widget.Resources.Examples")]
[Error("DIVIDE_BY_ZERO", 400, ErrorSeverity.Error, "Division by zero, %{num1} and %{num2}.")]
class CalculatorService : StandaloneService
{
   // Service logic and operations...
}

var channelMessage = new ChannelMessage(channelName, subject);
channelMessage.Data.Add("event", "ingest_started");
channelMessage.Data.Add("mobId", "060a2b340101010101010f0013-000000-475d870b9a6b24fb-060e2b347f7f-2a80");
// ...
bus.PostToChannel(channelMessage, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to post to channel: " + channelMessage.ChannelId + ", error: " + error.Message + ".");
    }
});

public interface IChannelMessageSubscriber
{
    void OnChannelMessage(IChannelContext channelContext);
}

public interface IChannelContext
{
    // The received message.
    ChannelMessage ChannelMessage { get; }

    // Instance of BusAccess appropriate for the lifetime of the channel message.
    IBusAccess BusAccess { get; }
}

**Note:** In versions of the API less than 2.5, the `IChannelSubscriber` interface was used to subscribe to channel messages (rather than `IChannelMessageSubscriber`).

bus.SubscribeToChannel(channelName, mySubscriber, new ChannelOptions("shared.name"), new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to subscribe to channel: " + channelName + ", error: " + error.Message + ".");
    }
});

var bindings = new List<String>();
bindings.Add("log.CalculatorService.*");
bindings.Add("log.*.info");
bindings.Add("log.*.warning");
bus.SubscribeToChannel(channelName, bindings, service, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to subscribe to channel: " + channelName + ", error: " + error.Message + ".");
    }
});

var bindings = new List<String>();
bindings.Add("log.*.info");
bindings.Add("log.*.warning");
bus.UnsubscribeFromBindings(loggingChannelName, bindings, mySubscriber, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to unsubscribe from channel: " + loggingChannelName + ", error: " + error.Message + ".");
    }
});

bus.UnsubscribeFromChannel(loggingChannelName, mySubscriber, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to unsubscribe from channel: " + loggingChannelName + ", error: " + error.Message + ".");
    }
});

bus.UnsubscribeFromChannels(mySubscriber, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to unsubscribe from all channels", error: " + error.Message + ".");
    }
});

bus.Zone("5b2123f1-3f8e-4fcb-9263-f7b98bbdab0c").PostToChannel(channelMessage, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to post to channel: " + channelMessage.ChannelId + ", error: " + error.Message + ".");
    }
});

bus.MultiZone.PostToChannel(channelMessage, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to post to channel: " + channelMessage.ChannelId + ", error: " + error.Message + ".");
    }
});

bus.MultiZone.SubscribeToChannel(channelName, mySubscriber, new AnonAsyncOpResult() {
    onError = (OperationError error) => {
        Console.WriteLine("Failed to subscribe to channel: " + channelName + ", error: " + error.Message + ".");
    }
});

using Avid.Platform.Bus.Messaging.CoreServices;

[Operation("subtract", "Returns the difference of two numbers.")]
[RestRequest("calculator/subtract")]
[return: Result("difference")]
public void Subtract(int a, int b, IOperationContext<int> responder)
{
    responder.Respond( a - b);
}

public interface IAsyncQueryResult : IAsyncOpResult {
    void OnTimeout();
}

public interface IAsyncOpResult
{
    void OnSuccess(object result);
    void OnError(OperationError error);
}

public class AnonAsyncOpResult : IAsyncOpResult {
    public Action onSuccess;        // This delegate doesn't accept a result parameter i.e. appropriate for "void" IAsyncOpResult operations.
    public Action<OperationError> onError;

    // ...
}

public class AnonAsyncOpResult<T> : IAsyncOpResult {
    public Action<T> onSuccess;
    public Action<OperationError> onError;

    // ...
}

public class AnonAsyncQueryResult : IAsyncQueryResult {
    public Action<Message> onSuccess;
    public Action<OperationError> onError;
    public Action onTimeout;

    // ...
}

// ...
var msg = new Message("avid.acs.calculator", "global.test", 3, "divide");
msg.Parameters.Add("num1", 12);
msg.Parameters.Add("num2", 3);
bus.Query(msg, new AnonAsyncQueryResult() {
    onSuccess = (Message result) => {
        int q = result.Results.GetItem & lt; int> ("quotient");
        Console.WriteLine("quotient = " + q + ".");
    },
    onError = (OperationError error) => {
        Console.WriteLine("Failed to query service: " + msg.ServiceType + ", error: " + error.Message + ".");
    },
    onTimeout = () => {
        Console.WriteLine("Timed-out querying service: " + msg.ServiceType + ".");
    }
});

// ...
bus.SubscribeToChannel("net.service.jobs", new string[] { "submit" }, new SubmitSubscriber(),
     new AnonAsyncOpResult() {
         onSuccess = () => {
             Console.WriteLine("Subscription to 'net.service.jobs':'submit' succeeded.");
         },
         onError = (OperationError error) => {
             Console.WriteLine("Subscription to 'net.service.jobs':'submit' failed: " + error.Message);
         }
     });

public void SubmitJob(int jobId, int execTime, IOperationContext<NetServiceResponse> response)
{
    if (jobId < 1)
    {
        IDictionary<string, string> parameters = new Dictionary<string, string>();
        parameters.Add("jobId", jobId.ToString());
        response.Error(new Error("INVALID_JOB_ID", parameters, "Invalid jobId was provided. Must be integer > 0."));
    } else if (execTime < 100)
    {
        IDictionary<string, string> parameters = new Dictionary<string, string>();
        parameters.Add("execTime", execTime.ToString());
        response.Error(new Error("INVALID_JOB_ID", parameters, "Invalid execution time provided. Must be integer >= 100."));
    } else
    {
        PostChannelMessages(response.BusAccess, jobId, execTime);
        SetNumberOfSubmittedJobsCallback setNumberOfSubmittedJobsCallback = new SetNumberOfSubmittedJobsCallback(response);
        GetNumberOfSubmittedJobsCallback getNumberOfSubmittedJobsCallback = new GetNumberOfSubmittedJobsCallback(this, setNumberOfSubmittedJobsCallback, response);
        GetNumberOfSubmittedJobs(response.BusAccess, getNumberOfSubmittedJobsCallback);
    }
}

private void PostChannelMessages(IBusAccess busAccess, int jobId, int execTime)
{
    ChannelMessage message = new ChannelMessage("net.service.jobs", "submit");
    message.Data.Add("jobId", jobId);

    try
    {
        busAccess.PostToChannel(message, new AnonAsyncOpResult() {
            onError = (OperationError error) => {
                Console.WriteLine("Post to channel 'net.service.jobs':'submit' failed: " + error.Message);
            }
        });
    }
    catch (BusAccessException e)
    {
        Console.WriteLine(e.Message);
    }

    System.Timers.Timer timer = new System.Timers.Timer();
    timer.Elapsed += (sender, e) => { MessageProcessed(busAccess, jobId); timer.Close(); };
    timer.Interval = execTime;
    timer.Enabled = true;
}