Gecko.NCore.Client 12.0.0-beta.4

About

Gecko.NCore.Client is a NuGet package for .NET based development with the Elements® Integration Services (EIS) APIs.

How it works

The NCore.Client is used to develop so-called EIS integrations. These are applications (apis/services/frontends) used to integrate Elements with domain- and/or customer-specific applications, e.g. to update Elements with archive-worthy data. EIS is based on the WCF framework and SOAP protocols.

It is intended to be a helpful tool for integrating parties to more easily perform the functions that the EIS offers. It provides LINQ support and strongly typing to the underlying object model.

NCore.Client provides these main APIs (services):

• ObjectModelService defines models for CRUD operations, as well as endpoints for running both predefined and ad hoc queries.
• FunctionService defines a set of specific functions in the caseworker, archiving and meeting domain.
• DocumentService defines operations for checking in and out documents, and to upload or download documents.
• MetadataService defines operations for retrieving metadata associated with specific object types and keys.

Token-based authentication

Authentication is handled via Elements.Authentication.Client. There are two usage modes:

Full EIS context (Gecko.NCore.Client) — access the full LINQ/adapter surface through IEisContextFactory and create contexts with EisContextIdentity:

services.AddEisContext(new EisContextOptions
{
    BaseAddress = "https://ncore.example.com",
    ExternalSystemName = "MySystem",
    Authentication = new EisAuthenticationOptions
    {
        ClientId = "...",
        AuthorityUrl = "https://authority.example.com",
        Scopes = ["..."]
    },
    ObjectModel = new AdapterRegistration<IAsyncObjectModelAdapter>(
        EisServiceAddresses.ObjectModelV3En,
        (identity, settings) => new AsyncObjectModelAdapterV3En(identity, settings))
});

Adapter registrations (ObjectModel, Functions, Documents, Metadata) are typed against the IAsyncXxxAdapter interfaces (e.g. IAsyncObjectModelAdapter). Since these derive from their synchronous counterparts (e.g. IAsyncObjectModelAdapter : IObjectModelAdapter), registering an async-capable adapter automatically enables both the synchronous (context.Query<T>(), context.Functions, ...) and asynchronous (context.Query<T>().ToListAsync(), context.FunctionsAsync, ...) surfaces on the resulting IEphorteContext.

public class MyService(IEisContextFactory factory)
{
    public async Task RunAsync()
    {
        var context = factory.Create(new EisContextIdentity { Username = "alice", Role = "Reader" });
        var persons = await context.Query<Person>().ToListAsync();
    }
}

Individual WCF proxy (e.g. Gecko.NCore.Client.Claims.V1) — access a single service endpoint through a dedicated factory:

services.AddClaimServiceClient(new ClaimServiceClientOptions
{
    BaseAddress = "https://ncore.example.com",
    Authentication = new EisAuthenticationOptions
    {
        ClientId = "...",
        AuthorityUrl = "https://authority.example.com",
        Scopes = ["..."]
    }
});

public class ClaimSyncService(IClaimServiceClientFactory factory)
{
    public async Task RunAsync()
    {
        using var client = factory.Create(new EisClientIdentity { Username = "alice" });
        // Use client here
    }
}

Each service-specific options class (e.g. ClaimServiceClientOptions) inherits from the shared EisClientOptions base, which carries BaseAddress, TenantId, HttpClientName, Authentication, RelativeServiceAddress, and an optional BindingFactory for custom WCF bindings.

Gecko.NCore.Client.Authentication — authentication-specific shared types:

• EisAuthenticationOptions — authentication configuration.

Gecko.NCore.Client.Context — context-specific types shared by the full EIS context API:

• EisContextIdentity — per-call identity for IEisContextFactory (username, role, tenant).
• EisContextOptions — configuration for AddEisContext and adapter registrations.
• AdapterRegistration<TAdapter> — adapter wiring for the context factories. TAdapter is expected to be one of the IAsyncXxxAdapter interfaces (e.g. IAsyncObjectModelAdapter), enabling both sync and async access from a single registered adapter instance.

Gecko.NCore.Client.ClientFactory — shared types used by the service-specific WCF proxy APIs:

• EisClientIdentity — per-call identity for individual WCF service proxies (username, tenant).
• EisClientOptions — base options class for individual WCF service proxy clients (BaseAddress, TenantId, HttpClientName, Authentication, RelativeServiceAddress, BindingFactory). Service-specific options classes (e.g. ClaimServiceClientOptions) inherit from it.
• EisClientOptions.BindingFactory (Func<Binding>?) - if provided, a fresh custom binding instance is created for each client.