SiLA2.AspNetCore 10.2.5

SiLA2.AspNetCore

ASP.NET Core Integration Utilities for SiLA2 Servers

SiLA2.AspNetCore is the integration layer between ASP.NET Core and the SiLA2 C# implementation, providing essential extension methods, configuration utilities, and dependency injection patterns for building production-ready SiLA2 gRPC servers.

This module simplifies server setup by automating common tasks like:

• Dependency injection configuration
• Kestrel web server setup with automatic TLS/SSL certificate handling
• SiLA2 feature initialization from .sila.xml files
• Writable configuration pattern for runtime settings updates
• Command-line argument parsing for server configuration

Package	SiLA2.AspNetCore (NuGet)
Repository	https://gitlab.com/SiLA2/sila_csharp
License	MIT
Target	.NET 10
Dependencies	SiLA2.Core, Microsoft.Extensions.Hosting.Abstractions

---

Key Features

• One-Line Server Setup - AddSiLA2Server() registers all essential services with a single call
• Extension Methods for Dependency Injection - Streamlined service registration with AddSiLA2CoreServices(), AddSiLA2CertificateServices(), and more
• Kestrel Server Configuration - Automatic TLS/SSL certificate handling with GetKestrelConfigData()
• Feature Auto-Discovery - Loads all .sila.xml feature definitions from the Features directory
• Writable Options Pattern - Runtime configuration updates that persist to appsettings.json
• Command-Line Argument Parsing - Override server IP, port, and certificate via CLI arguments
• Integration with SiLA2.Utils - Seamless connection to networking, security, and configuration services

---

Installation

NuGet Package Manager

Install-Package SiLA2.AspNetCore

.NET CLI

dotnet add package SiLA2.AspNetCore

Project Reference (Development)

<ItemGroup>
  <ProjectReference Include="..\SiLA2.AspNetCore\SiLA2.AspNetCore.csproj" />
</ItemGroup>

Note: This package is required for all ASP.NET Core-based SiLA2 servers. It depends on SiLA2.Core which will be installed automatically.

---

Quick Start

Here's a minimal SiLA2 server using ASP.NET Core with the AddSiLA2Server() extension method:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Extensions.DependencyInjection;
using SiLA2.AspNetCore;
using SiLA2.Server;
using YourFeature.Services;

var builder = WebApplication.CreateBuilder(args);

// Register all SiLA2 services with one call
builder.Services.AddSiLA2Server(builder.Configuration, options =>
{
    options.EnableGrpcReflection = true;  // Optional: enable for debugging
});

// Register feature services
builder.Services.AddSingleton<MyFeatureService>();

// Configure Kestrel with automatic certificate handling
builder.WebHost.ConfigureKestrel(options =>
{
    var (ipAddress, port, certificate) = args.GetKestrelConfigData(
        options.ApplicationServices);
    options.ConfigureEndpointDefaults(
        endpoints => endpoints.Protocols = HttpProtocols.Http1AndHttp2);
    options.Listen(ipAddress, port,
        listenOptions => listenOptions.UseHttps(certificate));
});

var app = builder.Build();

// Initialize SiLA2 features from Features/*.sila.xml files
var siLA2Server = app.Services.GetRequiredService<ISiLA2Server>();
app.InitializeSiLA2Features(siLA2Server);

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

// Start mDNS announcement
siLA2Server.Start();

app.Run();

Configuration (appsettings.json):

{
  "ServerConfig": {
    "Name": "MyDevice",
    "UUID": "12345678-1234-1234-1234-123456789012",
    "FQHN": "localhost",
    "Port": 50051
  }
}

Run the server:

dotnet run
# Or with custom IP/port:
dotnet run -- 192.168.1.100 50052

---

Extension Methods

AddSiLA2Server()

Registers all essential SiLA2 server services with a single call. This is the recommended way to configure a SiLA2 server.

Signature:

public static IServiceCollection AddSiLA2Server(
    this IServiceCollection services,
    IConfiguration configuration,
    Action<SiLA2ServerOptions> configureOptions = null)

Options:

• EnableBinaryTransfer - Enable upload/download repositories (default: false)
• EnableGrpcReflection - Enable gRPC reflection service (default: false)
• EnableDetailedErrors - Enable detailed gRPC errors (default: true)
• ServerConfigSectionName - Configuration section name (default: "ServerConfig")

Example:

var builder = WebApplication.CreateBuilder(args);

// Register all SiLA2 services with one call
builder.Services.AddSiLA2Server(builder.Configuration, options =>
{
    options.EnableBinaryTransfer = true;
    options.EnableGrpcReflection = true;
});

// Register feature-specific services
builder.Services.AddSingleton<MyFeatureService>();

Services Registered:

• gRPC with standard SiLA2 interceptors (Logging, MetadataValidation, ParameterValidation)
• MetadataManager for handling request/response metadata
• Network discovery services (ServiceDiscoveryInfo, ServerInformation, IServiceAnnouncer)
• Core server services (ISiLA2Server, IServerDataProvider, IGrpcChannelProvider)
• Certificate services (ICertificateProvider, ICertificateContext, ICertificateRepository)
• Observable command support (IObservableCommandManager<,>)
• IServerConfig from configuration

---

AddSiLA2Grpc()

Adds gRPC services with standard SiLA2 interceptors for logging, metadata validation, and parameter validation.

Signature:

public static IServiceCollection AddSiLA2Grpc(
    this IServiceCollection services,
    bool enableDetailedErrors = true)

Example:

// Use this if you need more control than AddSiLA2Server provides
services.AddSiLA2Grpc(enableDetailedErrors: true);

Interceptors Added:

• LoggingInterceptor - Logs all incoming requests and errors
• MetadataValidationInterceptor - Validates request metadata
• ParameterValidationInterceptor - Validates request parameters

---

AddSiLA2CoreServices()

Adds core SiLA2 server services. Use this if you need granular control over service registration.

Signature:

public static IServiceCollection AddSiLA2CoreServices(this IServiceCollection services)

Services Registered: | Service | Lifetime | |---------|----------| | MetadataManager | Singleton | | IObservableCommandManager<,> | Singleton (open generic) | | INetworkService | Transient | | ServiceDiscoveryInfo | Singleton | | ServerInformation | Singleton | | IServiceAnnouncer | Transient | | ISiLA2Server | Singleton | | IGrpcChannelProvider | Singleton | | IServerDataProvider | Scoped |

---

AddSiLA2CertificateServices()

Adds TLS/SSL certificate services for secure gRPC communication.

Signature:

public static IServiceCollection AddSiLA2CertificateServices(this IServiceCollection services)

Services Registered: | Service | Lifetime | |---------|----------| | ICertificateProvider | Singleton | | ICertificateContext | Singleton | | ICertificateRepository | Singleton |

---

AddSiLA2BinaryTransfer()

Adds binary transfer services for file upload and download functionality.

Signature:

public static IServiceCollection AddSiLA2BinaryTransfer(this IServiceCollection services)

Services Registered: | Service | Lifetime | |---------|----------| | IBinaryUploadRepository | Singleton | | IBinaryDownloadRepository | Singleton |

---

AddSiLA2ServerConfig()

Adds IServerConfig from the application configuration with writable options support.

Signature:

public static IServiceCollection AddSiLA2ServerConfig(
    this IServiceCollection services,
    IConfiguration configuration,
    string sectionName = "ServerConfig")

Required Configuration Values:

• Name - The server display name
• UUID - The server unique identifier (GUID)
• FQHN - The fully qualified host name or IP address
• Port - The server port number

Optional Configuration Values:

• NetworkInterface - The network interface to bind to
• DiscoveryServiceName - The mDNS service name

Example (appsettings.json):

{
  "ServerConfig": {
    "Name": "MyDevice",
    "UUID": "12345678-1234-1234-1234-123456789012",
    "FQHN": "localhost",
    "Port": 50051,
    "NetworkInterface": "0.0.0.0",
    "DiscoveryServiceName": "_sila2._tcp.local."
  }
}

---

GetKestrelConfigData()

Parses command-line arguments and retrieves Kestrel server configuration (IP address, port, TLS certificate).

Signature:

public static Tuple<IPAddress, int, X509Certificate2> GetKestrelConfigData(
    this string[] args,
    IServiceProvider serviceProvider)

Returns:

• Item1 - IPAddress to bind to (defaults to IPAddress.Any)
• Item2 - Port number
• Item3 - X509Certificate2 for TLS/SSL

Example:

builder.WebHost.ConfigureKestrel(options =>
{
    var (ipAddress, port, certificate) = args.GetKestrelConfigData(
        options.ApplicationServices);

    options.Listen(ipAddress, port, listenOptions =>
    {
        listenOptions.UseHttps(certificate);
    });
});

Command-Line Arguments:

# Override IP and port
dotnet run -- 127.0.0.1 50051

# Use default configuration
dotnet run

Requirements:

• ICertificateProvider must be registered in DI container
• IServerConfig must be registered in DI container

---

InitializeSiLA2Features()

Discovers and loads all .sila.xml feature definition files from the Features/ directory into the SiLA2 server.

Signature:

public static void InitializeSiLA2Features(
    this IHost host,
    ISiLA2Server siLA2Server)

Example:

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

// Load all Features/*.sila.xml files
app.InitializeSiLA2Features(siLA2Server);

// Now map gRPC services
app.MapGrpcService<TemperatureControllerService>();

Initialization Order (Critical):

1. builder.Build() → creates IHost
2. app.InitializeSiLA2Features(siLA2Server) → loads .sila.xml files
3. app.MapGrpcService<T>() → registers gRPC endpoints
4. siLA2Server.Start() → announces services via mDNS
5. app.Run() → starts server

What It Does:

1. Finds the assembly's Features/ subdirectory
2. Discovers all .sila.xml files
3. Loads feature definitions into the server for:
   • Parameter validation
   • Error handling
   • Metadata access
   • Server introspection

Feature Directory Structure:

MyServer.App/
├── Features/
│   ├── TemperatureController-v1_0.sila.xml
│   ├── DataTypeProvider-v1_0.sila.xml
│   └── SiLAService-v1_0.sila.xml
└── Program.cs

---

ConfigureWritable<T>()

Registers the writable options pattern, enabling runtime configuration updates that persist to appsettings.json.

Signature:

public static void ConfigureWritable<T>(
    this IServiceCollection services,
    IConfigurationSection section,
    string file = "appsettings.json") where T : class, new()

Example:

// In Program.cs
services.ConfigureWritable<ServerConfig>(
    configuration.GetSection("ServerConfig"),
    "appsettings.json");

// In a service
public class MyService
{
    private readonly IWritableOptions<ServerConfig> _settings;

    public MyService(IWritableOptions<ServerConfig> settings)
    {
        _settings = settings;
    }

    public void UpdateServerPort(int newPort)
    {
        // Updates configuration and persists to appsettings.json
        _settings.Update(config => config.Port = newPort);
    }

    public int GetCurrentPort()
    {
        return _settings.Value.Port;
    }
}

Configuration File Example (appsettings.json):

{
  "ServerConfig": {
    "Name": "TemperatureController",
    "UUID": "12345678-1234-1234-1234-123456789012",
    "FQHN": "localhost",
    "Port": 50051,
    "NetworkInterface": "0.0.0.0",
    "DiscoveryServiceName": "_sila2._tcp.local."
  }
}

---

Writable Options Pattern

The writable options pattern extends ASP.NET Core's standard options pattern by enabling runtime updates that persist to disk.

Standard Options vs. Writable Options

Standard Options (Read-Only):

public class MyService
{
    private readonly IOptions<ServerConfig> _options;

    public MyService(IOptions<ServerConfig> options)
    {
        _options = options;
        // Can only READ configuration
        var port = _options.Value.Port;
    }
}

Writable Options (Read-Write):

public class MyService
{
    private readonly IWritableOptions<ServerConfig> _options;

    public MyService(IWritableOptions<ServerConfig> options)
    {
        _options = options;
    }

    public void UpdateConfiguration()
    {
        // Can READ configuration
        var currentPort = _options.Value.Port;

        // Can WRITE configuration (persists to appsettings.json)
        _options.Update(config =>
        {
            config.Port = 8080;
            config.FQHN = "192.168.1.100";
        });
    }
}

Complete Example

1. Define Configuration Class:

public class ServerConfig
{
    public string Name { get; set; }
    public Guid UUID { get; set; }
    public string FQHN { get; set; }
    public int Port { get; set; }
}

2. Register Writable Options:

// In Program.cs
services.ConfigureWritable<ServerConfig>(
    configuration.GetSection("ServerConfig"),
    "appsettings.json");

3. Inject and Use:

public class ServerConfigurationService
{
    private readonly IWritableOptions<ServerConfig> _config;
    private readonly ILogger<ServerConfigurationService> _logger;

    public ServerConfigurationService(
        IWritableOptions<ServerConfig> config,
        ILogger<ServerConfigurationService> logger)
    {
        _config = config;
        _logger = logger;
    }

    public void ChangeServerPort(int newPort)
    {
        _config.Update(settings =>
        {
            settings.Port = newPort;
        });

        _logger.LogInformation($"Server port updated to {newPort}");
        // appsettings.json is now updated with new port
    }
}

How It Works:

1. Reads appsettings.json as JSON
2. Deserializes the specified section to type T
3. Applies your changes via the lambda
4. Serializes back to JSON
5. Writes to disk with indented formatting
6. Reloads configuration so all services see updated values

---

Complete Server Setup Example

Simplified Setup (Recommended)

Using AddSiLA2Server() for a clean, production-ready setup:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Extensions.DependencyInjection;
using SiLA2.AspNetCore;
using SiLA2.Server;
using YourFeature.Services;

var builder = WebApplication.CreateBuilder(args);

// ===== Configure Services =====
builder.Services.AddSiLA2Server(builder.Configuration, options =>
{
    options.EnableBinaryTransfer = true;
    options.EnableGrpcReflection = true;
    options.EnableDetailedErrors = true;  // Set false in production
});

// Feature services
builder.Services.AddSingleton<YourFeatureService>();
builder.Services.AddSingleton<LockControllerService>();
builder.Services.AddSingleton<AuthenticationService>();

// ===== Configure Kestrel =====
builder.WebHost.ConfigureKestrel(options =>
{
    var (ipAddress, port, certificate) = args.GetKestrelConfigData(
        options.ApplicationServices);

    options.ConfigureEndpointDefaults(
        endpoints => endpoints.Protocols = HttpProtocols.Http1AndHttp2);

    options.Listen(ipAddress, port, listenOptions =>
    {
        listenOptions.UseHttps(certificate);
    });
});

var app = builder.Build();

// ===== Configure Application =====
var siLA2Server = app.Services.GetRequiredService<ISiLA2Server>();
app.InitializeSiLA2Features(siLA2Server);

// Map gRPC services
app.MapGrpcService<SiLAService>();
app.MapGrpcService<YourFeatureService>();
app.MapGrpcService<LockControllerService>();
app.MapGrpcService<AuthenticationService>();

// Optional: gRPC reflection (if enabled)
app.MapGrpcReflectionService();

// Start mDNS announcement
siLA2Server.Start();

app.Run();

Advanced Setup (Fine-Grained Control)

For cases where you need precise control over service registration:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using SiLA2.AspNetCore;
using SiLA2.Commands;
using SiLA2.Server;
using SiLA2.Server.Services;
using SiLA2.Utils.Config;
using SiLA2.Utils.gRPC;
using SiLA2.Utils.Network;
using SiLA2.Utils.Security;
using YourFeature.Services;

var builder = WebApplication.CreateBuilder(args);

// ===== Configure Services =====
ConfigureServices(builder.Services, builder.Configuration);

// ===== Configure Kestrel =====
builder.WebHost.ConfigureKestrel(options =>
{
    var (ipAddress, port, certificate) = args.GetKestrelConfigData(
        options.ApplicationServices);

    options.ConfigureEndpointDefaults(
        endpoints => endpoints.Protocols = HttpProtocols.Http1AndHttp2);

    options.Listen(ipAddress, port, listenOptions =>
    {
        listenOptions.UseHttps(certificate);
    });
});

var app = builder.Build();

// ===== Configure Application =====
ConfigureApplication(app);

app.Run();

// ===== Service Registration =====
void ConfigureServices(IServiceCollection services, IConfiguration configuration)
{
    // Use individual extension methods for granular control
    services.AddSiLA2Grpc(enableDetailedErrors: true);
    services.AddSiLA2CoreServices();
    services.AddSiLA2CertificateServices();
    services.AddSiLA2BinaryTransfer();
    services.AddSiLA2ServerConfig(configuration);

    // Feature services
    services.AddSingleton<YourFeatureService>();
    services.AddSingleton<LockControllerService>();
    services.AddSingleton<AuthenticationService>();
}

// ===== Application Configuration =====
void ConfigureApplication(WebApplication app)
{
    var siLA2Server = app.Services.GetRequiredService<ISiLA2Server>();

    // Initialize features from Features/*.sila.xml
    app.InitializeSiLA2Features(siLA2Server);

    // Map gRPC services
    app.MapGrpcService<SiLAService>();
    app.MapGrpcService<YourFeatureService>();
    app.MapGrpcService<LockControllerService>();
    app.MapGrpcService<AuthenticationService>();

    // Optional: gRPC reflection for debugging
    app.MapGrpcReflectionService();

    // Start mDNS announcement
    siLA2Server.Start();
}

---

Command-Line Arguments

The GetKestrelConfigData() method parses command-line arguments to override server configuration.

Supported Arguments

Argument Position	Description	Example
1st argument	IP address or FQHN	127.0.0.1 or myserver.local
2nd argument	Port number	50051

Examples

# Default configuration from appsettings.json
dotnet run

# Override IP address
dotnet run -- 192.168.1.100

# Override IP and port
dotnet run -- 192.168.1.100 8080

# Use localhost
dotnet run -- 127.0.0.1 50051

Fallback Behavior

• If no IP is provided or IP parsing fails → IPAddress.Any (0.0.0.0)
• If no port is provided → Value from IServerConfig.Port
• Certificate is always loaded from ICertificateProvider

---

Integration with SiLA2.Utils

SiLA2.AspNetCore depends on services from SiLA2.Utils for core functionality:

Service	Purpose	Used By
ICertificateProvider	Loads/generates TLS certificates	GetKestrelConfigData()
IServerConfig	Server configuration (name, UUID, port, FQHN)	GetKestrelConfigData()
INetworkService	Network operations (IP resolution, interface discovery)	Feature services
IServiceAnnouncer	mDNS service announcement	ISiLA2Server.Start()

Dependency Chain:

SiLA2.AspNetCore
  └─ SiLA2.Core (SiLA2.dll)
      └─ SiLA2.Utils
          ├─ Security (ICertificateProvider)
          ├─ Config (IServerConfig)
          └─ Network (INetworkService, mDNS)

Example: Certificate Provider Registration:

// Register certificate provider
services.AddSingleton<ICertificateProvider, CertificateProvider>();
services.AddSingleton<ICertificateContext, CertificateContext>();
services.AddSingleton<ICertificateRepository, CertificateRepository>();

// Kestrel will automatically use the provider
builder.WebHost.ConfigureKestrel(options =>
{
    var (_, _, certificate) = args.GetKestrelConfigData(options.ApplicationServices);
    // certificate is loaded from ICertificateProvider
});

---

Working Examples

Explore complete working examples in the repository:

Temperature Controller Example

Path: src/Examples/TemperatureController/SiLA2.Temperature.Server.App/

Features:

• Complete ASP.NET Core setup with InitializeSiLA2Features()
• Kestrel configuration with command-line argument parsing
• Writable options for server configuration
• gRPC interceptors for validation and logging
• mDNS service announcement

Run:

cd src/Examples/TemperatureController/SiLA2.Temperature.Server.App
dotnet run

# With custom IP/port:
dotnet run -- 127.0.0.1 50051

Shaker Controller Example

Path: src/Examples/ShakerController/SiLA2.Shaker.Server.App/

Run:

cd src/Examples/ShakerController/SiLA2.Shaker.Server.App
dotnet run

Other Examples

• Data Type Provider: src/Examples/DataTypeProvider/
• Web Frontend Server: src/Examples/TemperatureController/SiLA2.Temperature.Server.App.Webfrontend/

---

Best Practices

1. Initialization Order

Always follow this sequence:

var app = builder.Build();                        // 1. Build host
app.InitializeSiLA2Features(siLA2Server);         // 2. Load .sila.xml files
app.MapGrpcService<MyFeatureService>();           // 3. Map gRPC endpoints
siLA2Server.Start();                              // 4. Announce via mDNS
app.Run();                                        // 5. Start server

2. Writable Options for Server Settings

Use writable options for configuration that needs runtime updates:

services.ConfigureWritable<ServerConfig>(
    configuration.GetSection("ServerConfig"),
    "appsettings.json");

3. Use AddSiLA2Server() for New Projects

// Recommended: registers all services with correct lifetimes
builder.Services.AddSiLA2Server(builder.Configuration);

// Only use individual methods if you need fine-grained control
services.AddSiLA2CoreServices();
services.AddSiLA2CertificateServices();

4. Enable Detailed Errors in Development

services.AddGrpc(options =>
{
    options.EnableDetailedErrors = true;  // Debug mode only
});

5. Use gRPC Interceptors

Add validation and logging interceptors:

services.AddGrpc(options =>
{
    options.Interceptors.Add<LoggingInterceptor>();
    options.Interceptors.Add<MetadataValidationInterceptor>();
    options.Interceptors.Add<ParameterValidationInterceptor>();
});

6. Feature Directory Structure

Place .sila.xml files in Features/ directory:

MyServer.App/
├── Features/
│   ├── MyFeature-v1_0.sila.xml      ← Feature definitions
│   └── AnotherFeature-v1_0.sila.xml
├── Services/
│   └── MyFeatureService.cs          ← Service implementations
└── Program.cs

7. Certificate Handling

Let ICertificateProvider manage certificates automatically:

services.AddSingleton<ICertificateProvider, CertificateProvider>();
// Automatically generates self-signed cert if none exists

8. Development vs. Production Configuration

Use different appsettings files:

#if DEBUG
    var configFile = "appsettings.Development.json";
#else
    var configFile = "appsettings.json";
#endif

services.ConfigureWritable<ServerConfig>(
    configuration.GetSection("ServerConfig"),
    configFile);

---

Additional Resources

• SiLA2 C# Wiki: https://gitlab.com/SiLA2/sila_csharp/-/wikis/home
• Main Repository: https://gitlab.com/SiLA2/sila_csharp
• SiLA Standard: https://sila-standard.com
• ASP.NET Core Documentation: https://learn.microsoft.com/aspnet/core
• gRPC for .NET: https://learn.microsoft.com/aspnet/core/grpc
• Open Issues: https://gitlab.com/SiLA2/sila_csharp/-/issues

---

Contribution

It's Open Source (License: MIT). Feel free to use or contribute!

Repository: https://gitlab.com/SiLA2/sila_csharp

Maintainer: Christoph Pohl (@Chamundi)