Integrating a .NET Application

Our .NET Finsemble Library allows you to integrate custom .NET applications into Finsemble. The .NET Library contains several methods to integrate an app with Finsemble and calls to many Finsemble APIs via remote procedure calls (RPC). The .NET Library also contains a user control to allow you to give WPF applications Finsemble's window management features and appearance. The minimum Finsemble version required is 2.3.

Our Finsemble .NET Seed Repository contains two sample .NET projects:

  • The WPFExample project contains a Finsemble-aware .NET application that has the WPF Window Title Bar user control, accepts drag and drop from Finsemble, and communicates over linker channels.
  • The AuthenticationExample project contains an example of using a .NET application to authenticate.

Adding a Finsemble-aware .NET application to the config

Finsemble-aware .NET applications are specified with a windowType of "FinsembleNativeWindow". Here is an example:

"My WPF Application": {
    "window": {
        "id": "My WPF Application",
        "windowType": "FinsembleNativeWindow",
    ...

You can use either an alias for a downloaded asset or a full path similar to assimilated windows.

Initializing a Finsemble-aware application

When a Finsemble-aware application is launched by Finsemble, several command line parameters are sent to the application. Those include:

  • finsembleWindowName
  • componentType
  • uuid
  • top
  • left
  • width
  • height
  • openfinVersion

These are required when you create the Finsemble object:

var FSBL = new Finsemble(args, this); //send arguments and the window to Finsemble
FSBL.Connect();
FSBL.Connected += Finsemble_Connected;

The application window InitializeComponent() is called after connecting to Finsemble:

private void Finsemble_Connected(object sender, EventArgs e)
{
    Application.Current.Dispatcher.Invoke((Action)delegate // Main thread
    {
        // Initialize this window and show it.
        InitializeComponent();
        FinsembleHeader.setBridge(FSBL); // The FinsembleHeader component requires a connected finsemble object to function.
        this.Show();
    });
}

Native Finsemble Clients

Currently, the Finsemble Linker Client and the Drag and Drop Client are available as Native Clients in .NET. Other client's functionality is available via the RPC call.

Using the Linker

Publish

Publish a piece of data. The data will be published to all channels that the component is linked to. Foreign components that are linked to those channels will receive the data if they have subscribed to this dataType. They can then use that data to synchronize their internal state. See Subscribe. You can publish to specific channels by specfying a channels array in the parameters.

FSBL.LinkerClient.Publish(new JObject {
    ["dataType"] = "symbol",
    ["data"]  = "AAPL"
});

Subscribe

Registers a client for a specific data type that is sent to a channel.

FSBL.LinkerClient.Subscribe("symbol", (sender, event) => {
    var symbol = event.response["data"];
});

Unsubscribe

Remove all listeners for the specified dataType.

FSBL.LinkerClient.Unsubscribe("symbol", (s, e) => { });

LinkToChannel

Add a component to a Linker channel programatically. Components will begin receiving any new contexts published to this channel but will not receive the currently established context.

FSBL.LinkerClient.LinkToChannel("group1", null, (s, e) => { });

UnlinkFromChannel

Unlinks a component from a Linker channel programatically.

FSBL.LinkerClient.UnlinkFromChannel("group1", null, (s, e) => { });

Using Drag and Drop

Emitters

To show the drag and drop icon in the Window Title Bar (see "WPF Window Title Bar" below), you must create an emitter. Here is the code from our sample application that shares a "symbol" object that contains the text from a TextBox called "DataToSend".

FSBL.DragAndDropClient.SetEmitters(new List<KeyValuePair<string, DragAndDropClient.emitter>>()
{
    new KeyValuePair<string, DragAndDropClient.emitter>("symbol", () =>
    {
    return new JObject
    {
        ["symbol"] = DataToSend.Text,
        ["description"] = "Symbol " + DataToSend.Text
    };
    })
});

Receivers

To allow data from Finsemble to be dropped onto your application, you must create receivers. Here is the code from our sample application that receives a "symbol" object and sets that as the text of the "DataToSend" TextBox.

FSBL.DragAndDropClient.AddReceivers(new List<KeyValuePair<string, EventHandler<FinsembleEventArgs>>>()
{
    new KeyValuePair<string, EventHandler<FinsembleEventArgs>>("symbol", (s, args) =>
    {
    var data = args.response["data"]?["symbol"]?["symbol"];
    if(data != null)
    {
        Application.Current.Dispatcher.Invoke((Action)delegate //main thread
        {
        DataToSend.Text = data.ToString();
        });
    };
    })
});

Scrim

When data to be shared in Finsemble is dragged, a scrim is displayed on top of all components denoting whether or not the component can receive that data. You must create a control (generally a label) that occupies the entire space of the component, sits on top of all other controls, and is hidden. This is the control that will accept the dragged data from other components. Here is how to provide this control to Finsemble:

// Assuming the control is called Scrim
FSBL.DragAndDropClient.SetScrim(Scrim);

WPF Window Title Bar

The WPF Window Title Bar user control provides Finsemble's built-in window management functionality to WPF components. By using this user control, .NET windows can participate in snapping and docking. Additionally, the WPF Window Title Bar allows the .NET component to link with other Finsemble components or utilize drag and drop data sharing.

Styling the Window Title Bar

You can change the background and button hover colors using the functions below. All the buttons are styled identically except the "close" button and the docked state background of the "docking" button.

// FinsembleHeader is the name of the WPFWindowTitleBar Control

FinsembleHeader.SetActiveBackground(new SolidColorBrush(Colors.Red)); //Background when window is active
FinsembleHeader.SetInactiveBackground(new SolidColorBrush(Colors.DarkRed)); //Background when window is inactive

FinsembleHeader.SetButtonHoverBackground(new SolidColorBrush(Colors.Purple)); //Button background on hover when window is active
FinsembleHeader.SetInactiveButtonHoverBackground(new SolidColorBrush(Colors.Yellow)); //Button background on hover when window is inactive

FinsembleHeader.SetCloseButtonHoverBackground(new SolidColorBrush(Colors.SeaShell)); //Close button background on hover when window is active
FinsembleHeader.SetInactiveCloseButtonHoverBackground(new SolidColorBrush(Colors.BurlyWood));// Close button background on hover when window is active

FinsembleHeader.SetDockingButtonDockedBackground(new SolidColorBrush(Colors.BlanchedAlmond)); // Docking button background when docked

FinsembleHeader.SetTitleForeground(new SolidColorBrush(Colors.LightGoldenrodYellow)); // Title text color
FinsembleHeader.SetButtonForeground(new SolidColorBrush(Colors.LightSalmon)); // Button text Color

Available Finsemble API endpoints via RPC

Here is the list of Finsemble API endpoints currently supported by the .NET Finsemble Library. Refer to the documentation of each endpoint in our API documentation:

Router Client

  • transmit
  • addListener
  • removeListener
  • query
  • publish
  • subscribe
  • unsubscribe

Launcher Client

  • showWindow
  • spawn

Config Client

  • getValue

Logger

  • error
  • warn
  • log
  • info
  • debug
  • verbose

While most RPC API calls are identical to the JavaScript calls, there are some with differences:

  • RouterClient.subscribe: This does not return a subscribeID.
  • RouterClient.unsubscribe: This takes the same parameters as subscribe above.
  • LinkerClient.publish: Does not use the callback. Does not support the "channels" option.
  • Logger API: All logs will be sent to Finsemble regardless of settings in the Central Logger

To use these endpoints, use the RPC function:

// Definition:
RPC(string endpoint, List<JToken> arguments, RPCCallBack callback)

The RPC call takes three parameters. The first one is the API enpoint. The second is a list of all the arguments to the API call that are specified in the JavaScript API documentation—except the callback or eventHandler. The third parameter is the callback or eventHandler. Here is an example showing the transmit API call for the Router Client:

FSBL.RPC("RouterClient.transmit", new List<JToken> {
    "channel", // First Paramter is the channel
    new JObject { // Second parameter is the data to send
    ["myData"] = "myData"
    }
},
(err, response) => {} // This is the eventHandler);

Authenticating with a .NET application

The main window of the AuthenticationExample application needs to be initialized the same way as a regular .NET Finsemble-aware window as described above. However, this authentication window cannot use the WPF Window Title Bar because the services are not available until authenticated. Once the user is authenticated, you need to call PublishAuthorization:

FSBL.RPC("AuthenticationClient.publishAuthorization", new JArray { username, credentials});

Getting user credentials

If your .NET app requires credentials from Finsemble, you can call GetCurrentCredentials:

FSBL.RPC("AuthenticationClient.getCurrentCredentials", new List<JObject>(), (err, credentials) => {
});

Further reading

For information about authentication, check out the Authentication Tutorial.

For information on making native applications into Finsemble components, read the Assimilation Tutorial.

Understanding how the Linker Client and Drag and Drop Client work is important for understanding this tutorial.