Raycynix.Extensions

Raycynix.Extensions is a set of infrastructure packages for .NET applications. The repository is organized as a modular collection of packages that can be combined selectively instead of pulling a single monolithic framework into every service.

What this repository contains

The solution is split by responsibility. The main package groups are:

• configuration and configuration abstractions
• contracts and contract integrations for ASP.NET Core
• database core, provider packages, hosting integration, and ASP.NET Core integration
• exceptions and exception handling integration
• logging
• messaging core plus transport-specific packages
• metrics, tracing, and observability
• security and secrets

Each package has its own README.md under src/<PackageName>/README.md with package-specific setup and usage examples.

Design principles

The packages in this repository follow a few consistent rules:

• composition over inheritance: infrastructure is added through DI registration and small extension packages
• explicit package boundaries: abstractions, core runtime, provider packages, and hosting adapters are separated
• provider registration over magic configuration: relational database providers are selected by adding the matching package and calling its registration method
• shared model composition: reusable packages can contribute EF Core configurators into a shared DatabaseContext
• provider-agnostic runtime behavior where possible: messaging persistence and database composition avoid hard-coding provider-specific behavior into the higher-level infrastructure layer

Database overview

The database module is split into several packages:

• Raycynix.Extensions.Database Contains the shared DatabaseContext, database configuration, configurator discovery, model caching, and IDatabaseInitializer.
• Raycynix.Extensions.Database.Sqlite
• Raycynix.Extensions.Database.PostgreSql
• Raycynix.Extensions.Database.MsSql
• Raycynix.Extensions.Database.MySql Each provider package wires EF Core to the matching relational database.
• Raycynix.Extensions.Database.Hosting Adds generic-host helpers for database initialization.
• Raycynix.Extensions.Database.AspNetCore Adds ASP.NET Core helpers for database initialization.

AddRaycynixDatabase(...) registers the shared infrastructure only. It does not select a provider by itself, and it does not initialize the database automatically.

Database setup

builder.Services
    .AddRaycynixDatabase(builder.Configuration, options =>
    {
        options.UseMigrations = true;
        options.EnsureCreated = false;
    })
    .AddPostgreSql();

If a package contributes EF Core configurators to the shared model, register its assembly explicitly:

builder.Services
    .AddRaycynixDatabase(builder.Configuration)
    .AddPostgreSql()
    .AddAssembly<SomeModelMarker>();

When assembly discovery must be controlled explicitly, disable automatic caller assembly registration:

builder.Services
    .AddRaycynixDatabase(builder.Configuration, registerCallerAssembly: false)
    .AddPostgreSql()
    .AddAssembly<IdentityModelMarker>()
    .AddAssembly<AuditModelMarker>();

This is useful in tests, plugin-style systems, or solutions where a single assembly may contain configurators with optional dependencies.

Database initialization

Initialization is performed by IDatabaseInitializer, which creates a scoped DatabaseContext and then:

1. runs EnsureCreatedAsync when EnsureCreated is enabled
2. runs MigrateAsync when UseMigrations is enabled

The hosting packages decide when this initializer should be executed.

ASP.NET Core

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddRaycynixDatabase(builder.Configuration, options =>
    {
        options.UseMigrations = true;
    })
    .AddPostgreSql();

var app = builder.Build();

await app.UseRaycynixDatabaseInitializationAsync();

app.Run();

Generic host

var builder = Host.CreateApplicationBuilder(args);

builder.Services
    .AddRaycynixDatabase(builder.Configuration, options =>
    {
        options.UseMigrations = true;
    })
    .AddPostgreSql();

var host = builder.Build();

await host.InitializeRaycynixDatabaseAsync();
await host.RunAsync();

Messaging overview

Raycynix.Extensions.Messaging contains the transport-agnostic messaging core. Transport packages such as Kafka, RabbitMQ, HTTP JSON, and gRPC attach concrete delivery mechanisms.

Raycynix.Extensions.Messaging.Database adds persistent inbox and outbox storage on top of the shared database infrastructure. It uses EF Core configurators registered into the shared DatabaseContext and relies on optimistic concurrency for inbox and outbox lease transitions rather than provider-specific SQL behavior in the messaging layer.

Package-level documentation

Start with these package READMEs for details:

• src/Raycynix.Extensions.Database/README.md
• src/Raycynix.Extensions.Database.Hosting/README.md
• src/Raycynix.Extensions.Database.AspNetCore/README.md
• src/Raycynix.Extensions.Messaging/README.md
• src/Raycynix.Extensions.Messaging.Database/README.md

The remaining packages follow the same pattern: core package, optional abstractions package, and optional hosting or transport adapters where needed.