SiLA2.Core 10.2.5

SiLA2.Core

C# Server Implementation of the SiLA2 Standard

SiLA Homepage	https://sila-standard.com
Chat group	Join the group on Slack
Maintainer	Christoph Pohl (@Chamundi)
Vulnerability Policy	https://sila-standard.com/vulnerability_policy

Overview

SiLA2.Core is the core server implementation for the SiLA2 laboratory automation standard. It provides:

• Platform-independent server infrastructure (Windows, Linux, macOS)
• Feature Definition Language (FDL) to Protocol Buffer transformation via XSLT
• Observable command lifecycle management with progress tracking
• mDNS service discovery for automatic server announcement
• Built-in core SiLA2 features (SiLAService, LockController, AuthenticationService, etc.)
• Binary transfer services for large data uploads and downloads
• Server-initiated connection support for cloud connectivity
• Metadata validation and authorization framework

Platform Support

Target Framework	Supported Platforms
.NET 10.0+	Windows, Linux, macOS (full feature support)
.NET Standard 2.0	.NET Framework 4.6.1+, .NET Core 2.0+, Mono 5.4+, Xamarin

Prerequisites

• Linux / macOS: .NET 10 SDK >> https://dotnet.microsoft.com/en-us/download/dotnet/10.0
• Windows: Visual Studio 2026 Community or later with .NET 10 SDK included

Installation

Install via NuGet Package Manager:

dotnet add package SiLA2.Core

Or via Package Manager Console:

Install-Package SiLA2.Core

Build your own Project based on SiLA2.Core

1. Create ASP.NET Core Application as SiLA2.Server Project
2. Reference SiLA2.Core (v10.2.3+) from NuGet.org
3. Create *.sila.xml Feature Files and include in MSBuild Targets

Recommended Approach (SiLA2.Core v10.2.3+)

The SiLA2.Core NuGet package automatically provides $(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>

Build and Test

• Build your Solution
• Run your SiLA2.Server.App
• Call Server from a Client or use the SiLA Universal Client
• If you have problems building, clean your NuGet cache: dotnet nuget locals all --clear

---

SiLA2.Core Services and Components

This section provides comprehensive documentation of all services, interfaces, and components provided by the SiLA2.Core assembly.

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:

// Register in DI container
services.AddSingleton<ISiLA2Server, SiLA2Server>();

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

// Start server (announces via mDNS)
siLA2Server.Start();

ServerInformation

Contains 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"
  }
}

ServerData

Container for server capabilities and metadata (used internally by core services).

---

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.

---

Domain Models and Feature Definitions

Feature Class

The auto-generated class representing a SiLA2 feature definition, extended with helper methods.

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

Utility class for deserializing feature definitions from XML files, streams, or online resources.

public class FeatureGenerator
{
    // Read from file
    static Feature ReadFeatureFromFile(string path);

    // Read from stream (embedded resources)
    static Feature ReadFeatureFromStream(Stream stream);

    // Read from URL
    static Feature ReadFeatureFromOnlineResource(string url);

    // Read from XML string
    static Feature ReadFeatureFromXml(string featureXML);
}

---

Validation and Error Handling

Validation Class

Validates parameter values against constraints defined in feature definitions.

// Validate a parameter value
Validation.ValidateParameter(value, feature, "CommandName", "ParameterName");

ErrorHandling Class

Factory methods for creating and raising SiLA2 errors via gRPC exceptions.

public class ErrorHandling
{
    // Raise errors (throws RpcException)
    static void RaiseSiLAError(SiLAError silaError, Metadata metadata = null);
    static void RaiseBinaryTransferError(ErrorType errorType, string message);

    // Create error objects
    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 errors from exceptions
    static SiLAError RetrieveSiLAError(RpcException e);
    static string HandleException(Exception e);
}

Usage:

// Raise a defined execution error
ErrorHandling.RaiseSiLAError(
    ErrorHandling.CreateDefinedExecutionError(
        feature.GetFullyQualifiedDefinedExecutionErrorIdentifier("InvalidTemperature"),
        "Temperature value out of range"));

// Raise a validation error
ErrorHandling.RaiseSiLAError(
    ErrorHandling.CreateValidationError(
        feature.GetFullyQualifiedCommandParameterIdentifier("SetTemperature", "Value"),
        "Value must be between 0 and 100"));

---

Core Services

SiLAService

The fundamental discovery service that all SiLA2 servers must implement.

Properties:

• ServerName - Configurable server display name
• ServerUUID - Unique server identifier
• ServerType, ServerDescription, ServerVendorURL, ServerVersion - Server metadata
• ImplementedFeatures - List of all feature FQIs

Commands:

• GetFeatureDefinition - Returns FDL XML for a specified feature
• SetServerName - Updates the server's display name

AuthenticationService / IAuthenticationInspector

Handles user authentication and token issuance.

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

// Register your implementation
services.AddSingleton<IAuthenticationInspector, MyAuthInspector>();

Commands:

• Login - Authenticates user and returns access token
• Logout - Revokes access token

AuthorizationService

Validates access tokens for protected resources.

LockControllerService / ILockControllerService

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

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

    // Observable lock status
    Task Subscribe_IsLocked(Subscribe_IsLocked_Parameters request,
        IServerStreamWriter<Subscribe_IsLocked_Responses> responseStream,
        ServerCallContext context);

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

CancelControllerService / ICancelControllerService

Enables cancellation of running observable commands.

PauseControllerService

Enables pausing and resuming of observable commands.

SimulationControllerService

Enables simulation mode for testing without physical hardware.

ParameterConstraintsProviderService

Provides runtime constraint information for command parameters.

ErrorRecoveryServiceImpl

Handles recoverable error states and recovery workflows.

---

Server-Initiated Connection Services

These services enable SiLA2 servers (devices behind firewalls) to connect outbound to SiLA2 clients (cloud services).

CloudEndPoint

Bidirectional streaming endpoint for server-initiated connections.

public class CloudEndPoint : CloudClientEndpoint.CloudClientEndpointBase
{
    // Establishes duplex stream with parallel send/receive tasks
    Task ConnectSiLAServer(
        IAsyncStreamReader<SiLAServerMessage> responseStream,
        IServerStreamWriter<SiLAClientMessage> requestStream,
        ServerCallContext context);
}

Critical Pattern: Uses 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
{
    // Client management
    Task<ConnectSiLAClient_Responses> ConnectSiLAClient(ConnectSiLAClient_Parameters request, ServerCallContext context);
    Task<DisconnectSiLAClient_Responses> DisconnectSiLAClient(DisconnectSiLAClient_Parameters request, ServerCallContext context);

    // Reconnection on startup
    Task ReconnectPersistedClientsAsync();

    // Known clients dictionary
    IDictionary<ClientConfig, CloudClientEndpointClient> KnownClients { get; }
}

ISiLAServerMessageService / SiLAServerMessageService

Processes incoming client messages and routes them to appropriate feature implementations.

public interface ISiLAServerMessageService
{
    ConcurrentQueue<SiLAServerMessage> ServerMessageResponses { get; }
    Task<SiLAServerMessage> ProcessSilaClientRequest(SiLAClientMessage siLAClientMessage);
}

ISiLAClientMessageService / SiLAClientMessageService

Manages client message queues for server-initiated connections.

ObservableCommandSubscriptionManager

Manages observable command lifecycle in server-initiated connection mode.

ObservablePropertySubscriptionManager

Manages observable property subscriptions in server-initiated connection mode.

ConnectionLifecycleManager (Optional)

Advanced connection management with automatic reconnection and health monitoring.

ConnectionHealthMonitor / ConnectionRetryPolicy (Optional)

Health monitoring and retry policies for robust connection handling.

---

Binary Transfer Services

SiLABinaryUploadService

Handles chunked binary data upload from clients (max 2 MiB chunks).

public class SiLABinaryUploadService : BinaryUpload.BinaryUploadBase
{
    // Create upload session
    Task<CreateBinaryResponse> CreateBinary(CreateBinaryRequest request, ServerCallContext context);

    // Stream chunks
    Task UploadChunk(
        IAsyncStreamReader<UploadChunkRequest> requestStream,
        IServerStreamWriter<UploadChunkResponse> responseStream,
        ServerCallContext context);

    // Cleanup
    Task<DeleteBinaryResponse> DeleteBinary(DeleteBinaryRequest request, ServerCallContext context);
}

SiLABinaryDownloadService

Handles chunked binary data download to clients.

IBinaryUploadRepository / BinaryUploadRepository

Thread-safe storage for uploaded binary chunks.

IBinaryDownloadRepository / BinaryDownloadRepository

Thread-safe storage for downloadable binary data.

---

Metadata Management

MetadataManager

Tracks metadata requirements and validates metadata in gRPC call headers.

public class MetadataManager
{
    // Collect metadata requirements from feature services
    void CollectMetadataAffections(Feature feature, object serviceInstance);

    // Query required metadata
    List<KeyValuePair<string, FeatureMetadata>> GetRequiredMetadataForCall(string methodName);
    List<KeyValuePair<string, FeatureMetadata>> GetRequiredMetadataForFullyQualifiedIdentifier(string fqi);
    List<string> GetAffectedCallsByMetadata(string fullyQualifiedMetadataId);
}

SilaClientMetadata

Utility class for handling SiLA client metadata in gRPC headers.

public class SilaClientMetadata
{
    // Get all metadata identifiers from request
    static List<string> GetAllSilaClientMetadataIdentifiers(Metadata metadata);

    // Get specific metadata value
    static byte[] GetSilaClientMetadataValue(Metadata metadata, string fullyQualifiedMetadataIdentifier);

    // Convert FQI to wire format
    static string ConvertMetadataIdentifierToWireFormat(string fullyQualifiedMetadataIdentifier);
}

---

Service Discovery (mDNS)

IServiceAnnouncer / ServiceAnnouncer

Announces SiLA2 server availability on the local network via mDNS (RFC 6762).

public interface IServiceAnnouncer : IDisposable
{
    void Start();
}

public class ServiceAnnouncer : IServiceAnnouncer
{
    ServiceProfile Profile { get; }
    IEnumerable<Tuple<IPAddress, int>> Endpoints { get; }
}

IServiceFinder / ServiceFinder

Discovers SiLA2 servers on the local network via mDNS queries.

ConnectionInfo / ServerDiscoveryInfo

Data classes for service discovery information.

---

Repositories

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();
}

AuthorizationTokenRepository

Manages access tokens for authenticated sessions.

---

gRPC Interceptors

ParameterValidationInterceptor

Validates request parameters against FDL constraints (extensible).

MetadataValidationInterceptor

Validates required metadata headers on incoming requests.

LoggingInterceptor

Logs gRPC method calls for diagnostics.

---

Quick Start Example

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

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

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

var app = builder.Build();

// Initialize SiLA2 features
var siLA2Server = app.Services.GetRequiredService<ISiLA2Server>();

// Map gRPC services
app.MapGrpcService<SiLAService>();
app.MapGrpcService<TemperatureControllerService>();

// Start server announcement
siLA2Server.Start();

app.Run();

---

For more Information

Visit the SiLA2 C# Wiki

Related Packages

• SiLA2.Client - Client-side gRPC communication
• SiLA2.Client.Dynamic - Runtime dynamic client generation
• SiLA2.AspNetCore - ASP.NET Core integration and DI extensions
• SiLA2.Utils - Network utilities, mDNS, certificates
• SiLA2.Database.SQL - EntityFramework Core integration
• SiLA2.Authentication - Authentication and certificate management