👁 Image
SiLA2.AspNetCore 10.2.4

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

Key Features

• Extension Methods for Dependency Injection - Streamlined service registration for SiLA2 components
• 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:

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

var builder = WebApplication.CreateBuilder(args);

// Register SiLA2 services
builder.Services.AddGrpc();
builder.Services.AddSingleton<ISiLA2Server, SiLA2Server>();
builder.Services.AddSingleton<ICertificateProvider, CertificateProvider>();
builder.Services.AddSingleton<IServerConfig>(new ServerConfig(
 name: "MyDevice",
 uuid: Guid.NewGuid(),
 fqhn: "localhost",
 port: 50051));

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

Run the server:

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

Extension Methods

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

Here's a production-ready SiLA2 server template:

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)
{
 // gRPC configuration
 services.AddGrpc(options =>
 {
 options.EnableDetailedErrors = true;
 options.Interceptors.Add<SiLA2.Server.Interceptors.LoggingInterceptor>();
 options.Interceptors.Add<SiLA2.Server.Interceptors.MetadataValidationInterceptor>();
 options.Interceptors.Add<SiLA2.Server.Interceptors.ParameterValidationInterceptor>();
 });

 // Core SiLA2 services
 services.AddSingleton<ISiLA2Server, SiLA2Server>();
 services.AddSingleton<IGrpcChannelProvider, GrpcChannelProvider>();
 services.AddSingleton(typeof(IObservableCommandManager<,>),
 typeof(ObservableCommandManager<,>));

 // Security and networking
 services.AddSingleton<ICertificateProvider, CertificateProvider>();
 services.AddSingleton<ICertificateContext, CertificateContext>();
 services.AddTransient<INetworkService, NetworkService>();

 // Server configuration
 var serverConfig = new ServerConfig(
 name: configuration["ServerConfig:Name"],
 uuid: Guid.Parse(configuration["ServerConfig:UUID"]),
 fqhn: configuration["ServerConfig:FQHN"],
 port: int.Parse(configuration["ServerConfig:Port"]),
 networkInterface: configuration["ServerConfig:NetworkInterface"],
 discoveryServiceName: configuration["ServerConfig:DiscoveryServiceName"]);
 services.AddSingleton<IServerConfig>(serverConfig);

 // Writable options for runtime configuration updates
 services.ConfigureWritable<ServerConfig>(
 configuration.GetSection("ServerConfig"),
 "appsettings.json");

 // 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

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:

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. Register ISiLA2Server as Singleton

services.AddSingleton<ISiLA2Server, SiLA2Server>();
// NOT AddScoped or AddTransient

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)