SiLA2.Core 10.2.6

SiLA2.Core

The foundational library of the SiLA2 C# SDK

Overview

SiLA2.Core is the shared foundation that the rest of the SiLA2 C# SDK is built on. It is not a server-only package — it is referenced by clients, dynamic clients, the communication layer, ASP.NET Core integration, feature assemblies and tooling alike. Anything that needs to understand a SiLA2 Feature Definition, resolve fully-qualified identifiers, validate values against constraints, translate SiLA errors, or discover servers on the network depends on it.

It provides two layers:

1. Shared building blocks — used by every SiLA2 role (client, server, dynamic client, tooling):

• Feature Definition Language (FDL) domain model and parsing (Feature, FeatureGenerator)
• Fully-qualified identifier (FQI) construction and lookup helpers
• Parameter validation against FDL constraints
• SiLA error creation and parsing (servers raise, clients interpret)
• mDNS service discovery — announcing (servers) and finding (clients)
• Metadata utilities and binary-transfer contracts

2. Server hosting infrastructure — used when you build a SiLA2 server:

• Platform-independent server host (ISiLA2Server / SiLA2Server)
• Observable command lifecycle management with progress tracking
• Built-in core features (SiLAService, LockController, AuthenticationService, …)
• Binary transfer services and server-initiated ("cloud") connectivity

Where SiLA2.Core is used

SiLA2.Core is a direct dependency of the other SiLA2 packages, on both sides of the wire:

Because of this, most consumers pull in SiLA2.Core transitively — you typically reference SiLA2.Client or SiLA2.AspNetCore and get SiLA2.Core with it. You only reference it directly when writing a feature assembly or working against the domain model itself.

Platform Support

SiLA2.Core multi-targets net10.0 and netstandard2.0 so the same package can back a modern .NET 10 server and a .NET Framework client application.

Installation

Install via NuGet Package Manager:

dotnet add package SiLA2.Core

Or via Package Manager Console:

Install-Package SiLA2.Core

Shared Building Blocks

The following components are used regardless of whether you are writing a client, a server, a dynamic client, or tooling.

Feature Definitions (FDL)

Feature Class

The domain representation of a SiLA2 feature definition, extended with helper methods. Clients use it to understand a server's capabilities; servers use it to validate incoming calls.

public partial class Feature
{
    // Fully qualified identifier (e.g., "org.silastandard/core/SiLAService/v1")
    public string FullyQualifiedIdentifier { get; }

    // gRPC namespace for generated stubs
    public string Namespace { get; }

    // FQI construction methods
    string GetFullyQualifiedCommandIdentifier(string commandIdentifier);
    string GetFullyQualifiedCommandParameterIdentifier(string commandId, string parameterId);
    string GetFullyQualifiedPropertyIdentifier(string propertyIdentifier);
    string GetFullyQualifiedDefinedExecutionErrorIdentifier(string errorIdentifier);
    string GetFullyQualifiedMetadataIdentifier(string metadataIdentifier);

    // Element retrieval
    List<FeatureCommand> GetDefinedCommands();
    List<FeatureProperty> GetDefinedProperties();
    List<FeatureDefinedExecutionError> GetDefinedExecutionErrors();
    List<FeatureMetadata> GetDefinedMetadata();

    // Element lookup by FQI
    object GetMatchingElement(string fullyQualifiedIdentifier);
}

FeatureGenerator

Deserializes feature definitions from XML files, streams, or online resources — equally useful in a server (loading the features it hosts) and in a client (introspecting a server's features).

public class FeatureGenerator
{
    static Feature ReadFeatureFromFile(string path);            // from file
    static Feature ReadFeatureFromStream(Stream stream);        // from embedded resource
    static Feature ReadFeatureFromOnlineResource(string url);   // from URL
    static Feature ReadFeatureFromXml(string featureXML);       // from XML string
}

Parameter Validation

Validates values against constraints defined in a feature — a server validates inbound parameters, a client can validate before sending.

Validation.ValidateParameter(value, feature, "CommandName", "ParameterName");

Error Handling

Factory methods to create and raise SiLA2 errors (server side) and to parse them back out of gRPC exceptions (client side).

public class ErrorHandling
{
    // Create / raise (server side)
    static void RaiseSiLAError(SiLAError silaError, Metadata metadata = null);
    static void RaiseBinaryTransferError(ErrorType errorType, string message);
    static SiLAError CreateDefinedExecutionError(string errorIdentifier, string message);
    static SiLAError CreateUndefinedExecutionError(string message);
    static SiLAError CreateValidationError(string parameter, string message);
    static SiLAError CreateFrameworkError(ErrorType errorType, string message);

    // Parse (client side)
    static SiLAError RetrieveSiLAError(RpcException e);
    static string HandleException(Exception e);
}

Server side — raise a defined execution error:

ErrorHandling.RaiseSiLAError(
    ErrorHandling.CreateDefinedExecutionError(
        feature.GetFullyQualifiedDefinedExecutionErrorIdentifier("InvalidTemperature"),
        "Temperature value out of range"));

Client side — interpret an error returned by a server:

try
{
    await client.SetTemperatureAsync(request);
}
catch (RpcException ex)
{
    SiLAError silaError = ErrorHandling.RetrieveSiLAError(ex);
    // inspect silaError.DefinedExecutionError / ValidationError / FrameworkError
}

Service Discovery (mDNS)

SiLA2 servers announce themselves and clients find them, both via mDNS (RFC 6762). The announcer is the server-side half; the finder is the client-side half.

// Client side — discover servers on the local network
public interface IServiceFinder { /* query available SiLA2 servers */ }

// Server side — announce this server's availability
public interface IServiceAnnouncer : IDisposable
{
    void Start();
}

ConnectionInfo / ServerDiscoveryInfo are the data classes describing a discovered server (host, port, capabilities) and are consumed primarily by clients.

Metadata Utilities

SilaClientMetadata handles SiLA client metadata carried in gRPC headers — clients attach it, servers read it.

public class SilaClientMetadata
{
    static List<string> GetAllSilaClientMetadataIdentifiers(Metadata metadata);
    static byte[] GetSilaClientMetadataValue(Metadata metadata, string fullyQualifiedMetadataIdentifier);
    static string ConvertMetadataIdentifierToWireFormat(string fullyQualifiedMetadataIdentifier);
}

Client-Side Usage

You normally talk to a server through SiLA2.Client or SiLA2.Client.Dynamic, both of which build on SiLA2.Core. The Core pieces a client relies on directly are: discovery (IServiceFinder), feature introspection (FeatureGenerator / Feature), FQI helpers, and error parsing (ErrorHandling.RetrieveSiLAError).

// Read a server's feature definition to understand its capabilities
Feature feature = FeatureGenerator.ReadFeatureFromOnlineResource(
    "https://server.example/features/TemperatureController-v1_0.sila.xml");

foreach (var command in feature.GetDefinedCommands())
    Console.WriteLine(feature.GetFullyQualifiedCommandIdentifier(command.Identifier));

// After a gRPC call, translate any failure into a structured SiLA error
try { /* client.SomeCallAsync(...) */ }
catch (RpcException ex)
{
    var silaError = ErrorHandling.RetrieveSiLAError(ex);
    // handle defined / validation / framework error
}

For the full client experience (channel creation, typed/dynamic invocation, streaming subscriptions) see the SiLA2.Client and SiLA2.Client.Dynamic packages.

Building a SiLA2 Server

This section covers the server-hosting half of SiLA2.Core. For a complete server you will also reference SiLA2.AspNetCore for the ASP.NET Core hosting integration.

Core Server Infrastructure

ISiLA2Server / SiLA2Server

The main server interface and implementation for hosting SiLA2 features.

public interface ISiLA2Server
{
    ServerInformation ServerInformation { get; }
    MetadataManager MetadataManager { get; }
    List<string> ImplementedFeatures { get; }

    void Start();
    Feature GetFeature(string featureIdentifier);
    Feature ReadFeature(string featureDefinitionFile);
    Feature ReadFeature(string resourceName, Type implementationType);
    Feature GetFeatureOfElement(string fullyQualifiedIdentifier);
}

Usage:

services.AddSingleton<ISiLA2Server, SiLA2Server>();

var feature = siLA2Server.ReadFeature(
    Path.Combine("Features", "MyFeature-v1_0.sila.xml"));

siLA2Server.Start();  // announces via mDNS

ServerInformation

Static metadata about the SiLA2 server instance.

public class ServerInformation
{
    public string Type { get; }        // Make/Model of the device
    public string Description { get; } // Server capabilities description
    public string VendorURI { get; }   // Vendor website URL
    public string Version { get; }     // Server software version
}

Configuration via appsettings.json:

{
  "ServerInfo": {
    "Type": "TemperatureController",
    "Description": "A SiLA2 temperature controller server",
    "VendorURI": "https://example.com",
    "Version": "1.0.0"
  }
}

Building a Feature Assembly (FDL → Proto → C#)

Feature assemblies reference SiLA2.Core and transform *.sila.xml FDL files into .proto (via XSLT) and then C# gRPC stubs (via protoc) at build time. From v10.2.3+ the SiLA2.Core NuGet package supplies $(SiLA2XsltPath) and $(SiLA2ProtoPath) via MSBuild props:

<Target Name="ProtoPreparation" BeforeTargets="PrepareForBuild">
  
  <Error Condition="'$(SiLA2XsltPath)' == ''" Text="SiLA2XsltPath is not set. Ensure SiLA2.Core NuGet package v10.2.3+ is referenced." />

  <Message Text="Copying Base Protos..." Importance="high" />
  <Copy SourceFiles="$(SiLA2ProtoPath)SiLAFramework.proto" DestinationFolder="Protos/" />

  <Message Text="Started XmlTransformation TemperatureController-v1_0.sila.xml -> TemperatureController.proto" Importance="high" />
  <XslTransformation XslInputPath="$(SiLA2XsltPath)fdl2proto.xsl" XmlInputPaths="$(MSBuildProjectDirectory)/Features/TemperatureController-v1_0.sila.xml" OutputPaths="Protos/TemperatureController.proto" />
  <Message Text="Finished XmlTransformation" Importance="high" />
</Target>

<Target Name="ProtoGeneration" DependsOnTargets="ProtoPreparation" AfterTargets="ProtoPreparation">
  <Message Text="Compiling Protos..." Importance="high" />
  <ItemGroup>
    <Protobuf Include="Protos\TemperatureController.proto" ProtoRoot="Protos\" GrpcServices="Both" OutputDir="Services\" />
    <Protobuf Update="Protos\SiLAFramework.proto" ProtoRoot="Protos\" CompileOutputs="false" />
  </ItemGroup>
  <Message Text="Finished Compiling Protos..." Importance="high" />
</Target>

Observable Command Management

IObservableCommandManager<TParameter, TResponse>

Manages the lifecycle of long-running observable commands with progress tracking.

public interface IObservableCommandManager<TParameter, TResponse>
{
    bool IsCommandMapBusy { get; }

    Task<ObservableCommandWrapper<TParameter, TResponse>> AddCommand(
        TParameter parameter,
        Func<IProgress<ExecutionInfo>, TParameter, CancellationToken, TResponse> func,
        TimeSpan executionDelay = default,
        bool isQueued = false);

    ObservableCommandWrapper<TParameter, TResponse> GetCommand(CommandExecutionUUID cmdExecId);

    Task RegisterForInfo(
        CommandExecutionUUID cmdExecId,
        IServerStreamWriter<ExecutionInfo> responseStream,
        CancellationToken cancellationToken);

    Task ProcessIntermediateResponses<TIntermediateResponse>(
        CommandExecutionUUID cmdExecId,
        IServerStreamWriter<TIntermediateResponse> responseStream,
        Action<TParameter, CancellationToken> handler,
        CancellationToken token);
}

Observable Command Pattern:

public class MyFeatureService : MyFeature.MyFeatureBase
{
    private readonly IObservableCommandManager<Parameters, Response> _commandManager;

    public override async Task<CommandConfirmation> MyObservableCommand(
        Parameters request, ServerCallContext context)
    {
        var command = await _commandManager.AddCommand(request, WorkerFunction);
        return command.Confirmation;
    }

    public override async Task MyObservableCommand_Info(
        CommandExecutionUUID cmdExecId,
        IServerStreamWriter<ExecutionInfo> responseStream,
        ServerCallContext context)
    {
        await _commandManager.RegisterForInfo(cmdExecId, responseStream, context.CancellationToken);
    }

    private Response WorkerFunction(
        IProgress<ExecutionInfo> progress,
        Parameters parameters,
        CancellationToken cancellationToken)
    {
        for (int i = 0; i <= 100; i += 10)
        {
            progress.Report(new ExecutionInfo
            {
                CommandStatus = i == 100
                    ? ExecutionInfo.Types.CommandStatus.FinishedSuccessfully
                    : ExecutionInfo.Types.CommandStatus.Running,
                ProgressInfo = new Real { Value = i / 100.0 }
            });
            Thread.Sleep(500);
        }
        return new Response { /* result */ };
    }
}

ObservableCommandWrapper<TParameter, TResponse>

Wraps command execution state, providing access to the CommandConfirmation, result, and completion status.

Built-in Core Services

SiLAService

The fundamental discovery service that all SiLA2 servers must implement.

Properties: ServerName, ServerUUID, ServerType, ServerDescription, ServerVendorURL, ServerVersion, ImplementedFeatures Commands: GetFeatureDefinition (returns FDL XML for a feature), SetServerName

AuthenticationService / IAuthenticationInspector

Handles user authentication and token issuance.

public interface IAuthenticationInspector
{
    Task<bool> IsAuthenticated(Login_Parameters request);
}

services.AddSingleton<IAuthenticationInspector, MyAuthInspector>();

Commands: Login, Logout

AuthorizationService

Validates access tokens for protected resources.

LockControllerService / ILockControllerService

Provides exclusive access control to server features, commands, and properties.

public class LockControllerService : LockController.LockControllerBase
{
    Task<LockServer_Responses> LockServer(LockServer_Parameters request, ServerCallContext context);
    Task<UnlockServer_Responses> UnlockServer(UnlockServer_Parameters request, ServerCallContext context);

    Task Subscribe_IsLocked(Subscribe_IsLocked_Parameters request,
        IServerStreamWriter<Subscribe_IsLocked_Responses> responseStream,
        ServerCallContext context);

    void CheckLock(Metadata metadata);
    void AddLockableItems(List<string> items);
}

Additional Controllers

• CancelControllerService — cancellation of running observable commands
• PauseControllerService — pausing and resuming of observable commands
• SimulationControllerService — simulation mode for testing without physical hardware
• ParameterConstraintsProviderService — runtime constraint information for parameters
• ErrorRecoveryServiceImpl — recoverable error states and recovery workflows

Metadata Management (server side)

MetadataManager

Tracks metadata requirements and validates metadata in gRPC call headers.

public class MetadataManager
{
    void CollectMetadataAffections(Feature feature, object serviceInstance);
    List<KeyValuePair<string, FeatureMetadata>> GetRequiredMetadataForCall(string methodName);
    List<KeyValuePair<string, FeatureMetadata>> GetRequiredMetadataForFullyQualifiedIdentifier(string fqi);
    List<string> GetAffectedCallsByMetadata(string fullyQualifiedMetadataId);
}

gRPC Interceptors

• ParameterValidationInterceptor — validates request parameters against FDL constraints
• MetadataValidationInterceptor — validates required metadata headers on incoming requests
• LoggingInterceptor — logs gRPC method calls for diagnostics

Server Quick Start

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<IServiceAnnouncer, ServiceAnnouncer>();
builder.Services.AddSingleton<MetadataManager>();
builder.Services.AddSingleton<ServerInformation>(sp =>
    new ServerInformation(builder.Configuration));
builder.Services.AddSingleton<ISiLA2Server, SiLA2Server>();

// Your feature services
builder.Services.AddSingleton<TemperatureControllerService>();

var app = builder.Build();
var siLA2Server = app.Services.GetRequiredService<ISiLA2Server>();

app.MapGrpcService<SiLAService>();
app.MapGrpcService<TemperatureControllerService>();

siLA2Server.Start();  // announce via mDNS
app.Run();

Tip: if you have problems building, clear your NuGet cache: dotnet nuget locals all --clear

Binary Transfer Services

Used by both clients and servers for payloads larger than the gRPC message limit (chunked, max 2 MiB per chunk). SiLA2.Core provides the server-side services and repositories.

SiLABinaryUploadService

public class SiLABinaryUploadService : BinaryUpload.BinaryUploadBase
{
    Task<CreateBinaryResponse> CreateBinary(CreateBinaryRequest request, ServerCallContext context);
    Task UploadChunk(
        IAsyncStreamReader<UploadChunkRequest> requestStream,
        IServerStreamWriter<UploadChunkResponse> responseStream,
        ServerCallContext context);
    Task<DeleteBinaryResponse> DeleteBinary(DeleteBinaryRequest request, ServerCallContext context);
}

• SiLABinaryDownloadService — chunked binary download to clients
• IBinaryUploadRepository / BinaryUploadRepository — thread-safe storage for uploaded chunks
• IBinaryDownloadRepository / BinaryDownloadRepository — thread-safe storage for downloadable data

Server-Initiated ("Cloud") Connections

These services enable SiLA2 servers (devices behind firewalls) to connect outbound to SiLA2 clients (cloud services), reversing the usual direction.

CloudEndPoint

Bidirectional streaming endpoint for server-initiated connections.

public class CloudEndPoint : CloudClientEndpoint.CloudClientEndpointBase
{
    Task ConnectSiLAServer(
        IAsyncStreamReader<SiLAServerMessage> responseStream,
        IServerStreamWriter<SiLAClientMessage> requestStream,
        ServerCallContext context);
}

Critical pattern: dual-task architecture with separate send and receive loops running in parallel to handle continuous streaming from observable properties and commands.

ConnectionConfigurationService

Manages client connections for server-initiated connection mode.

public class ConnectionConfigurationService : ConnectionConfigurationServiceBase
{
    Task<ConnectSiLAClient_Responses> ConnectSiLAClient(ConnectSiLAClient_Parameters request, ServerCallContext context);
    Task<DisconnectSiLAClient_Responses> DisconnectSiLAClient(DisconnectSiLAClient_Parameters request, ServerCallContext context);
    Task ReconnectPersistedClientsAsync();
    IDictionary<ClientConfig, CloudClientEndpointClient> KnownClients { get; }
}

Supporting services: ISiLAServerMessageService / SiLAServerMessageService, ISiLAClientMessageService / SiLAClientMessageService, ObservableCommandSubscriptionManager, ObservablePropertySubscriptionManager, and the optional ConnectionLifecycleManager / ConnectionHealthMonitor / ConnectionRetryPolicy for automatic reconnection and health monitoring.

IClientConfigurationRepository / ClientConfigurationRepository

Persists client configurations for server-initiated connections.

public interface IClientConfigurationRepository
{
    Task SaveClientAsync(ClientConfiguration config);
    Task RemoveClientAsync(string clientName);
    Task<ClientConfiguration> GetClientAsync(string clientName);
    Task<IEnumerable<ClientConfiguration>> GetAllClientsAsync();
    Task<bool> ClientExistsAsync(string clientName);
    Task ClearAllAsync();
}

For more Information

Visit the SiLA2 C# Wiki

Related Packages

• SiLA2.Client — client-side gRPC communication (typed clients)
• SiLA2.Client.Dynamic — runtime dynamic client generation (no compile-time stubs)
• SiLA2.Communication — dynamic protobuf and marshalling
• SiLA2.AspNetCore — ASP.NET Core hosting integration and DI extensions
• SiLA2.Utils — network utilities, mDNS, certificates
• SiLA2.Database.SQL — EntityFramework Core integration
• SiLA2.Authentication — authentication and certificate management