It is recommended that you implement the IExceptionHandler interface so that your application can handle exceptions generated by StreamLink. Such an exception generally indicates that the internal state of the StreamLink library can no longer be relied upon as being correct, unless the exception inherits from RecoverableStreamLinkException (see below).

In most cases StreamLink will only propagate an exception to the IExceptionHandler if it indicates an unrecoverable error, allowing you to shut down and restart the application in an appropriate manner. However in some cases an exception will be propagated to the IExceptionHandler for informational purposes, in which case an application restart is not required. It is recommended that your implementation of IExceptionHandler should check if the exception passed to it inherits from RecoverableStreamLinkException, and if so you may wish to take a different course of action.

If the exception passed to your exception handler is not recoverable then your exception handler should shut the application down gracefully, since the only way to recover from the exception is to restart the application. There is no need to log the exception in the handler because StreamLink logs it through the ILogger before passing it to the IExceptionHandler.

The application must register the IExceptionHandler with StreamLink by setting the ExceptionHandler property of the StreamLink object. If you do not implement and register an IExceptionHandler, StreamLink will continue to run when it encounters an internal exception, but its behaviour will be unpredictable.

CopyC#

using System;
using System.Collections.Generic;
using System.Text;

using Caplin.StreamLink;
using Caplin.StreamLink.Authentication;

namespace StreamLinkExamples.Basics
{
    /// <summary>
    /// Example inner class that implements IExceptionHandler and
    /// a an outline of how it may be used.
    /// </summary>
    public class SettingUpAnExceptionHandler
    {
        /// <summary>
        /// An example of how to set up a very basic exception handler.
        /// </summary>
        public static void SettingUpAnExceptionHandlerExample()
        {
            // Create a basic StreamLink instance
            IStreamLink myStreamLink = new StreamLink();

            // Set up the exception handler
            myStreamLink.ExceptionHandler = new ExampleExceptionHandler();
        }

        /// <summary>
        /// Example class that implements IExceptionHandler
        /// </summary>
        private class ExampleExceptionHandler: IExceptionHandler
        {
            /// <summary>
            /// IExceptionHandler method called when an unexpected exception
            /// occurs within the StreamLink library.
            /// </summary>
            /// <param name="ex">The exception.</param>
            public void HandleException(Exception ex)
            {
                // Clean up application

                // Warn the user about the error and that the application is
                // to close

                // Close the application
            }
        }
    }
}

The IExceptionHandler methods are not called on a dedicated worker thread. They are called directly from a thread running within the StreamLink library.