How to...

Overview

All io.Connect .NET functionalities are available for your Blazor WebAssembly and Blazor Server apps through the io.Connect .NET library for .NET Standard library.

Your interop-enabled Blazor apps can be defined as io.Connect apps (see App Definition) in order to be started by io.Connect Desktop and hosted in io.Connect Windows, or they can run independently in a browser.

For the differences in initializing the io.Connect library in hosted and browser Blazor apps, see the Hosted & Browser Apps section.

Blazor apps started by io.Connect Desktop will be hosted in io.Connect Windows enabling them to stick to other io.Connect Windows, to use Channels, and to be saved and restored in Layouts.

Blazor WebAssembly

The connection to io.Connect in a Blazor WebAssembly app originates from the client app (the browser webpage) which means that the Blazor WebAssembly app will behave as a desktop app and will connect to the locally installed io.Connect Desktop.

See the Blazor WebAssembly example on GitHub which demonstrates the various io.Connect Desktop features.

Blazor Server

If you plan on using the io.Connect .NET library for .NET Standard in Blazor Server apps, consider that the connection to io.Connect will originate from the server side. This means that you can either install the io.Connect Gateway on a visible location (cloud), or use the Blazor server on the desktop machine (e.g., Docker, IIS) where you have a running io.Connect Desktop. For Blazor Server apps, you can integrate the front-end with the io.Connect JavaScript library.

Referencing

The io.Connect .NET library for .NET Standard is available as a NuGet package which you can include and configure in your projects. Download and reference the latest version.

See the Blazor examples on GitHub demonstrating the various io.Connect Desktop features.

Initialization

To initialize the io.Connect .NET library for .NET Standard, you can use the GlueProvider demo class from the Blazor examples that demonstrates all necessary initialization logic and can be modified or used as is, per your needs.

For more in-depth examples of initializing the library, see the Hosted & Browser Apps section.

The GlueProvider class supports:

io.Connect initialization for Blazor WebAssembly and Blazor Server apps hosted in io.Connect Desktop.
io.Connect initialization for Blazor WebAssembly and Blazor Server apps opened in a browser.
Blazor logging facade.

The following example demonstrates how to plug in the GlueProvider class in your Blazor app:

// Bridging the logger.
builder.Services.AddScoped<IGlueLoggerFactory, GlueLoggerFactory>(serviceProvider =>
                new GlueLoggerFactory(serviceProvider.GetService<ILoggerFactory>()));

// Plugging in the `GlueProvider` class.
builder.Services.AddScoped(typeof(GlueProvider));

After that, you can use io.Connect in your RAZOR file:

Injection:

@inject IGlueLoggerFactory GlueLoggerFactory
@inject GlueProvider glueProvider

Initialization:

@code {
   private Task<IGlue42Base> GetGlue()
        => glueProvider.InitGlue();
}

The following example demonstrates how to use the io.Connect APIs after the initialization of the library:

// Getting the io.Connect object - entry point for all io.Connect APIs.
var io = await GetGlue().ConfigureAwait(false);

// Using the Channels API to join a Channel and update its context.
var redChannel = await io.Channels
    .AwaitChannel(channel => channel.Name == "Red").ConfigureAwait(false);

context = io.Channels.JoinChannel(redChannel);

await context.SetValue(ric, "partyPortfolio.ric").ConfigureAwait(false);

All concepts are demonstrated in the Blazor examples.

Hosted & Browser Apps

When initializing the io.Connect .NET library for .NET Standard in Blazor apps, you have to consider whether your app is defined as an io.Connect app and can be started by io.Connect Desktop, or is running independently in a browser. In the different scenarios you will need different mechanisms for providing authentication and app information to io.Connect. In the case of a hosted Blazor app, io.Connect Desktop injects this information in the io.Connect Window and you must expose a function to extract it. In the case of a Blazor app running in a browser, this information must be provided manually through user input.

Hosted Apps

If your Blazor WebAssembly or Blazor Server app is hosted in io.Connect Desktop, you must expose a JavaScript function that will pull the necessary information from the io.Connect Window and then initialize the io.Connect library with it.

See a demo implementation of the exposed JavaScript function in the Blazor WebAssembly example.

The following example demonstrates how to invoke the exposed function:

initOptions = await Glue42Base.GetHostedGDOptions(
    async tokenName => await jsRuntime_.InvokeAsync<string>(tokenName).ConfigureAwait(false),
    async gdInfoPropName =>
    {
        var gdHostInfo = await GetJSProp<GDHostInfo>(gdInfoPropName).ConfigureAwait(false);
        windowId = gdHostInfo.WindowId;
        return gdHostInfo;
    }).ConfigureAwait(false);

Browser Apps

If your Blazor app is opened in a browser window, you must provide the username, the io.Connect authentication details and the app name yourself:

var username = await GetPromptInput("user name").ConfigureAwait(false);
var appName = await GetPromptInput("app name").ConfigureAwait(false);

initOptions = new InitializeOptions
{
    AdvancedOptions = new AdvancedOptions
    {
        AuthenticationProvider = new GatewaySecretAuthenticationProvider(username, username)
    },
    // Make sure that the app name is different for each scoped `GlueProvider`.
    ApplicationName = appName
};

Initialization

When you have built the initialization options using either mechanism, initialize the io.Connect library to obtain the io.Connect object - the entry point for all io.Connect APIs:

var io = await Glue42Base.InitializeGlue(initOptions).ConfigureAwait(false);

Socket Implementation

For Blazor WebAssembly apps, you have to select an appropriate socket implementation. Otherwise, it isn't necessary to change the socket implementation:

// Choosing socket implementation appropriate for Blazor WebAssembly apps.
initOptions.AdvancedOptions.SocketFactory = connection =>
    new ClientSocket(new Uri(initOptions.GatewayUri ?? DefaultGatewayUri), new Configuration());

Logging

You can choose your own logging facade and then create a bridge so that io.Connect will log through your logging mechanism.

See the demo logging implementation in the Blazor WebAssembly example.

Implement the bridging contract and instruct io.Connect to use your logging mechanism:

initOptions.LoggerFactory = your_logging_factory;

The Blazor examples use the Microsoft logging mechanism plugged in the following way:

builder.Services.AddScoped<IGlueLoggerFactory, GlueLoggerFactory>(serviceProvider =>
    new GlueLoggerFactory(serviceProvider.GetService<ILoggerFactory>()));

App Definition

To add your Blazor app to the io.Connect launcher, you must create a JSON file with app definition. Place this file in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/apps folder, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO).

The following is an example definition of a Blazor app:

{
    "name": "my-app",
    "title": "My App",
    "type": "window",
    "details": {
        "url": "https://example.com/my-app/",
        "mode": "tab",
        "width": 500,
        "height": 400
    }
}

The "name", "type" and "url" properties are required and "type" must be set to "window". The "url" property points to the location of the web app.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and as a window title if the web app doesn't have a document title.

For more details, see the Developers > Configuration > Application section.

io.Connect .NET Concepts

Once the io.Connect .NET library has been initialized, your app has access to all io.Connect functionalities. For more detailed information on the different io.Connect capabilities and APIs, see: