CovenirBPO.AxiomFabric 1.1.0

.NET 9.0

dotnet add package CovenirBPO.AxiomFabric --version 1.1.0

NuGet\Install-Package CovenirBPO.AxiomFabric -Version 1.1.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="CovenirBPO.AxiomFabric" Version="1.1.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="CovenirBPO.AxiomFabric" Version="1.1.0" />
                    

                            Directory.Packages.props

<PackageReference Include="CovenirBPO.AxiomFabric" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add CovenirBPO.AxiomFabric --version 1.1.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: CovenirBPO.AxiomFabric, 1.1.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package CovenirBPO.AxiomFabric@1.1.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=CovenirBPO.AxiomFabric&version=1.1.0
                    

                            Install as a Cake Addin

#tool nuget:?package=CovenirBPO.AxiomFabric&version=1.1.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CovenirBPO.AxiomFabric

A standardized Azure Service Bus-based communication system for distributed .NET applications.

Overview

The Axiom Fabric library provides a robust communication framework for distributed .NET applications, enabling:

Module Integration: Register your application as a fabric module with automatic health reporting
Dashboard Monitoring: Build monitoring dashboards to view and control all fabric modules
Docker Container Management: Manage Docker containers across multiple VMs with built-in lifecycle commands
Command Handling: Send and receive commands across the fabric
Health Reporting: Automatic heartbeats and detailed health metrics
Environment Isolation: Built-in environment filtering prevents cross-environment control (Production, Dev, Test, Stage)
Cross-Communication Prevention: Built-in isolation using FabricInstanceId, Environment, and TenantId
Lifecycle Management: Track module lifecycle states (Starting, Running, Stopping, etc.)

Installation

dotnet add package CovenirBPO.AxiomFabric

Current Version: 1.0.1
Target Framework: .NET 9.0

Quick Start - Module Integration

using CovenirBPO.AxiomFabric.Core;
using CovenirBPO.AxiomFabric.Module.Extensions;
using Azure.Messaging.ServiceBus;

var builder = WebApplication.CreateBuilder(args);

// Register Service Bus client
var connectionString = Environment.GetEnvironmentVariable("AZURE_SERVICE_BUS_CONNECTION_STRING");
builder.Services.AddSingleton(sp => new ServiceBusClient(connectionString));
builder.Services.AddSingleton(sp => new ServiceBusAdministrationClient(connectionString));

// Add Axiom Fabric Module Client
builder.Services.AddAxiomFabricModule(options =>
{
    options.FabricInstanceId = Guid.Parse("your-fabric-instance-id");
    options.Environment = FabricEnvironment.Prod;  // Prod, Dev, Test, or Stage
    options.ModuleId = Guid.Parse("your-module-id");
    options.ModuleCommonName = "MyModule";
    options.ModuleType = ModuleType.CustomerModule;
    options.Capabilities = ModuleCapabilities.HealthReporting | ModuleCapabilities.CustomCommands;
});

var app = builder.Build();

// Register module on startup
var moduleClient = app.Services.GetRequiredService<IFabricModuleClient>();
await moduleClient.RegisterModuleAsync();

app.Run();

Need DI inside command handlers? Build the host first, resolve IFabricModuleClient, and register handlers with the new extension methods (see Docs/Guides/AdvancedCommandHandlers.md). Each invocation gets its own DI scope, so scoped services stay safe.

Quick Start - Dashboard Integration

using CovenirBPO.AxiomFabric.Dashboard.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();

// Register Service Bus client
var connectionString = Environment.GetEnvironmentVariable("AZURE_SERVICE_BUS_CONNECTION_STRING");
builder.Services.AddSingleton(sp => new ServiceBusClient(connectionString));
builder.Services.AddSingleton(sp => new ServiceBusAdministrationClient(connectionString));

// Add Axiom Fabric Dashboard Client
builder.Services.AddAxiomFabricDashboard(options =>
{
    options.FabricInstanceId = Guid.Parse("your-fabric-instance-id");
    options.Environment = FabricEnvironment.Prod;  // IMPORTANT: Set to match your deployment
    options.StaleThreshold = TimeSpan.FromMinutes(3);
    options.OfflineThreshold = TimeSpan.FromMinutes(10);
});

var app = builder.Build();
app.Run();

Quick Start - Docker Controller Module

using CovenirBPO.AxiomFabric.Core;
using CovenirBPO.AxiomFabric.Module.Extensions;
using CovenirBPO.AxiomFabric.Docker.Extensions;
using Azure.Messaging.ServiceBus;

var builder = Host.CreateApplicationBuilder(args);

// Register Service Bus clients
var connectionString = Environment.GetEnvironmentVariable("AZURE_SERVICE_BUS_CONNECTION_STRING");
builder.Services.AddSingleton(sp => new ServiceBusClient(connectionString));
builder.Services.AddSingleton(sp => new ServiceBusAdministrationClient(connectionString));

// Register Docker client (auto-detects Windows/Linux)
builder.Services.AddDockerClient();

// Register Docker Controller configuration and services
builder.Services.AddDockerController(options =>
{
    options.ConfigurationPath = @"C:\Configuration\appsettings.json";
    options.EnableHotReload = false; // Recommended for production
});

// Register Axiom Fabric Module with Docker command handlers
builder.Services.AddAxiomFabricModule(options =>
{
    options.FabricInstanceId = Guid.Parse("your-fabric-instance-id");
    options.Environment = FabricEnvironment.Prod;
    options.ModuleId = Guid.Parse("your-module-id");
    options.ModuleInstanceId = Guid.NewGuid(); // Unique per instance
    options.ModuleType = ModuleType.DockerControllerModule;
    options.ModuleCommonName = $"Docker Controller - {Environment.MachineName}";
    options.Capabilities = ModuleCapabilities.HealthReporting | ModuleCapabilities.CustomCommands;
    
    // Register all Docker command handlers
    options.AddDockerControllerHandlers(builder.Services.BuildServiceProvider());
});

var host = builder.Build();

// Register module on startup
var moduleClient = host.Services.GetRequiredService<IFabricModuleClient>();
await moduleClient.RegisterModuleAsync();

await host.RunAsync();

Key Features

Module Client (`IFabricModuleClient`)

Automatic heartbeat sending (configurable interval)
Detailed health reporting with metrics
Custom command handler registration
Lifecycle state management
Module descriptor advertising
Built-in system commands (Ping, GetStatus, GetHealth)

Dashboard Client (`IFabricDashboardClient`)

View all registered modules
Monitor module health and lifecycle states
Send commands to modules (single instance, module, type, or broadcast)
Environment-filtered Docker Controller discovery (NEW in v1.0.1)
Stale/offline detection
In-memory state caching with retention
Admin dashboard support with cross-environment visibility

Docker Controller Features

Configuration-driven container management - Manage containers via JSON configuration
7 lifecycle commands - Start, Stop, Restart, Remove, GetStatus, GetLogs, PullImage
Dynamic container discovery - Dashboard queries controller for managed containers
Multi-VM support - Each controller manages containers on its host VM
Health monitoring - Background Docker daemon connectivity checks
Hot-reload configuration - Optional file watching for config changes
Environment isolation - Controllers only appear in matching environment dashboards
Single source of truth - No duplicate configuration needed

Security & Validation

Environment isolation (v1.0.1) - Dashboards see only matching environment controllers
Connection string validation (never logs secrets)
Envelope structure validation
Command targeting validation
Fabric/Environment/Tenant isolation
Fail-fast behavior on configuration errors
Managed module validation (Docker Controllers)

What's New in v1.0.1

?? SECURITY FIX - Environment Isolation for Docker Controllers

Critical Bug Fix: Dashboard could see and control Docker Controllers from ALL environments
NEW: Dashboards now see ONLY Docker Controllers matching their environment
- Production dashboard ? Only Production controllers
- Dev dashboard ? Only Development controllers
- Test dashboard ? Only Test controllers
- Stage dashboard ? Only Stage controllers
Admin Dashboard Support: Use includeAllEnvironments: true for cross-environment visibility
Unknown Environment Warning: Console warning if dashboard environment is not configured

Breaking Change: GetDockerControllersAsync() now filters by dashboard environment by default.
See Migration Guide for details.

Prerequisites

.NET 9.0 or higher
Azure Service Bus namespace
Environment variable: AZURE_SERVICE_BUS_CONNECTION_STRING
(Docker Controller only) Docker.DotNet package and Docker daemon access

Documentation

Core Guides

Docker Controller Guides

Docker Integration Guide - Complete Docker Controller implementation
Dashboard Docker Integration Guide - Dashboard-side Docker features
Migration Guide (v1.0.1) - Environment filtering breaking changes

Package Dependencies

Azure.Messaging.ServiceBus (7.18.2) - Azure Service Bus messaging
Docker.DotNet (3.125.15) - Docker daemon communication
Microsoft.Extensions.Hosting.Abstractions (9.0.0) - Hosting infrastructure
Microsoft.Extensions.Options (9.0.0) - Options pattern support
System.Text.Json (9.0.0) - JSON serialization
Microsoft.Data.Sqlite (9.0.0) - Local state persistence

License

MIT License - see LICENSE file for details

Support

For issues or questions, please open an issue on the GitHub repository.

Product	Compatible and additional computed target framework versions.
.NET	net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net9.0
- Azure.Messaging.ServiceBus (>= 7.18.2)
- Docker.DotNet (>= 3.125.15)
- Microsoft.Data.Sqlite (>= 9.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 9.0.0)
- Microsoft.Extensions.Options (>= 9.0.0)
- System.Text.Json (>= 9.0.0)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.1.0	223	2/21/2026
1.0.4	393	12/19/2025
1.0.3	257	12/19/2025
1.0.2	328	12/18/2025
1.0.2-rc1	313	12/18/2025
1.0.2-beta6	309	12/17/2025
1.0.2-beta5	305	12/17/2025
1.0.2-beta4	306	12/17/2025
1.0.2-beta3	306	12/17/2025
1.0.2-beta2	317	12/17/2025
1.0.2-beta1	466	12/9/2025
1.0.1	235	11/25/2025
1.0.0	472	11/18/2025
1.0.0-beta8	332	11/11/2025
1.0.0-beta7	323	11/10/2025
1.0.0-beta6	229	11/7/2025
1.0.0-beta5	234	11/6/2025
1.0.0-beta4	234	11/6/2025
1.0.0-beta3	233	11/5/2025
1.0.0-beta2	220	11/5/2025

v1.1.0:
ARCHITECTURAL OPTIMIZATION RELEASE - Reduce Service Bus message volume by ~80%

All new features default to OFF for zero-risk upgrades. No breaking changes.

Phase 1 - Message Volume Reduction:
- Change-based heartbeats: Only send heartbeats on status transitions, with configurable keepalive interval (opt-in via UseChangeBasedHeartbeats)
- Reactive descriptor resend: Disable periodic 5-min descriptor resend (opt-in via EnablePeriodicDescriptorResend = false)
- Dashboard threshold guidance: XML doc recommendations for StaleThreshold/OfflineThreshold when using change-based heartbeats
- Impact: ~80% heartbeat reduction, ~99% descriptor reduction for 50 modules

Phase 2 - Customer Data Communication Hardening:
- Configurable retry with exponential backoff for timeout failures (MaxRetryAttempts, BaseRetryDelay)
- Configurable handshake timeout (HandshakeTimeout in CustomerDataSenderOptions)
- Token store resilience: Max 100 active tokens with periodic cleanup timer
- SecurityException (wrong key) never retried - only TimeoutException triggers retry

Phase 4 - Command System Quality-of-Life:
- Dashboard command extensions: PingAsync, GetHealthAsync, SendCommandAsync convenience methods
- Default command timeout: Apply timeout to commands without explicit expiration (DefaultCommandTimeout)

Phase 5 - Dashboard Event/Trigger System:
- Reactive event system: HealthStatusChanged, ModuleWentStale, ModuleWentOffline, ModuleCameOnline, ErrorReported, UnhandledExceptionReported, LifecycleChanged, ModuleRegistered
- Per-event-type per-module cooldowns to prevent alert storms
- Background monitor service for stale/offline transition detection
- Zero overhead when not configured (AddDashboardEvents() opt-in)

Recommended upgrade path:
1. Update NuGet package - zero behavior change
2. Update dashboard thresholds (StaleThreshold=8min, OfflineThreshold=15min)
3. Enable change-based heartbeats per module
4. Enable reactive descriptors
5. Enable customer data retries

v1.0.4:
Added Communications Settings to IFabricSettings interface as it should always be required.
(NOTE) This may cause a breaking change for clients that implemented IFabricSettings previously.
v1.0.2 and v1.0.3:
Added Customer Communication to support external messaging outside of core Fabric functionality.
this allows us to send metadata and updates to systems like customer dashboards, email notification systems,
error monitoring platforms, etc.
- New Interfaces added to represent Fabric settings, Communications settings, and Dashboard settings in coonsuming clients (v1.0.3)
🐛 MINOR BUG FIXES AND IMPROVEMENTS:

v1.0.1:
🔒 SECURITY FIX - Environment Isolation for Docker Controllers

🐛 CRITICAL BUG FIX:
- Fixed: Dashboard could see and control Docker Controllers from ALL environments
- Security Risk: Production dashboards could control Dev/Test containers (and vice versa)
- Impact: High - Cross-environment control was possible in multi-environment deployments

✨ NEW SECURITY FEATURE - Automatic Environment Filtering:
- Dashboards now see ONLY Docker Controllers matching their environment
- Production dashboard → Only Production controllers
- Dev dashboard → Only Development controllers
- Test dashboard → Only Test controllers
- Stage dashboard → Only Stage controllers
- Automatic isolation - no configuration required

🔧 NEW CAPABILITIES:
- IFabricDashboardClient.Environment property exposes dashboard's configured environment
- includeAllEnvironments parameter for admin dashboards needing cross-environment visibility
- Explicit environment query support: GetDockerControllersAsync(FabricEnvironment.Dev)
- Unknown environment detection with console warning for misconfiguration
- Consistent filtering across all discovery methods

⚠️ BREAKING CHANGE (Medium Impact):
- GetDockerControllersAsync() now filters by dashboard environment (default behavior changed)
- Admin dashboards MUST add includeAllEnvironments: true to see all environments
- Unknown environment now triggers console warning (indicates misconfiguration)

📝 MIGRATION GUIDE:

✅ NO CHANGES NEEDED IF:
- Your dashboard and controllers are in the same environment
- You have environment-specific dashboards (Prod dashboard monitors Prod only)
- Your dashboard is correctly configured with explicit environment

⚠️ CHANGES REQUIRED IF:
- Admin dashboard needs to see ALL environments:
var controllers = await dashboard.GetDockerControllersAsync(includeAllEnvironments: true);
- Dashboard has Environment = Unknown:
Set explicit environment in appsettings.json: "Environment": "Prod"

📚 DOCUMENTATION:
- See Docs/Guides/MigrationGuide-beta17-EnvironmentFiltering.md for complete migration steps
- See Docs/Guides/DashboardDockerIntegration.md for troubleshooting
- Updated with environment filtering section and comprehensive troubleshooting guide

🧪 TESTING:
- 18 new comprehensive environment filtering tests
- 324 total tests passing (100% pass rate)
- Full coverage: environment isolation, admin overrides, Unknown handling, edge cases

🔐 SECURITY REVIEW:
- No bypass scenarios identified
- All filter paths verified
- Edge cases comprehensively tested
- Approved for production use

🎯 AFFECTED METHODS:
- GetDockerControllersAsync() - now filters by environment (breaking)
- GetDockerControllerByHostname() - respects environment filter
- GetHealthyDockerControllers() - filters by environment AND health
- GetDockerControllersByHost() - groups by environment-filtered controllers
- New overload: GetDockerControllersAsync(FabricEnvironment) for targeted queries

💡 UPGRADE RECOMMENDATION:
- HIGH PRIORITY for multi-environment deployments (security fix)
- MEDIUM PRIORITY for single-environment deployments (no functional change)
- Review migration guide before upgrading admin dashboards

Previous stable release:

v1.0.0:
🚀 STABLE RELEASE
- Graduated from beta to first stable production release
- Dynamic Docker container discovery (GetManagedContainers) now core feature
- Unified configuration (controller is single source of truth)
- Production-ready Docker Controller lifecycle command set
- Robust reporting subsystem (history streaming, retention, aggregation)
- Built-in system commands always available (Ping, GetStatus, GetHealth)
- Mandatory CorrelationId for all command requests/responses
- Sticky health states + text metrics support for richer diagnostics
- Automatic Azure Service Bus provisioning during startup
- Configuration auto-loading via hosted service (fail-fast on invalid config)
- Comprehensive documentation: Docker integration, dashboard, reporting guides
- Backward-compatible with latest beta (no additional migration required beyond prior notes)

Previous beta history retained below for reference:

v1.0.0-beta16:
🔥 CRITICAL DESIGN FIX - Container Discovery

🐛 MAJOR FIX:
- Fixed: Eliminated duplicate configuration between controller and dashboard
- Added: GetManagedContainers command for dynamic container discovery
- Dashboard now queries controller for managed containers automatically
- Single source of truth: Controller configuration only

✨ NEW FEATURES:
- GetManagedContainers command returns full container list
- DashboardDockerExtensions.GetManagedContainersAsync() helper methods
- ManagedContainerInfo response model with container metadata
- DockerManagedContainersResponse for structured results
- Automatic container discovery (no dashboard config needed)

🚨 BREAKING CHANGES:
- Dashboard must remove container mapping configuration (if present)
- Must use GetManagedContainersAsync() to discover containers
- Old approach (manual config) no longer recommended or documented

📝 MIGRATION:
- Remove DockerDashboard:ContainerMappings section from dashboard appsettings.json (if exists)
- Replace manual container lists with: var containers = await client.GetManagedContainersAsync(controllerId);
- Controller configuration remains unchanged
- Eliminates maintenance overhead of keeping two configs in sync

📚 DOCUMENTATION:
- DashboardDockerIntegration.md will be updated in next release
- GetManagedContainers command fully documented with XML comments
- Helper methods include comprehensive usage examples

v1.0.0-beta13:
PHASE 13 DOCKER CONTROLLER - Critical Fix

🐛 BUG FIX:
- Fixed: Docker Controller configuration not loading automatically on startup
- Added: DockerControllerConfigurationLoader hosted service
- Configuration now loads automatically when using AddDockerController()
- No manual LoadConfiguration() call required anymore

✨ IMPROVEMENT:
- Configuration loader runs as an IHostedService during application startup
- Fail-fast behavior: Application won't start if configuration is invalid
- Better logging for configuration loading status

📝 MIGRATION from beta12:
- Remove any manual calls to configService.LoadConfiguration()
- Configuration loads automatically during host startup
- Update to latest NuGet package: 1.0.0-beta13

v1.0.0-beta12:
PHASE 13 DOCKER CONTROLLER IMPLEMENTATION COMPLETE

🎉 NEW FEATURES:
- Complete Docker Controller implementation (22 production files)
- Configuration-driven container management
- 7 Docker command handlers (Start, Stop, Restart, Remove, GetStatus, GetLogs, PullImage)
- Health monitoring with Docker daemon connectivity checks
- Hot-reload configuration support
- Extension methods for easy DI setup
- Dashboard helper methods for controller discovery
- Comprehensive validation (configuration and commands)

📦 COMPONENTS:
- DockerControllerConfigurationService - Thread-safe config management
- DockerHealthCheckService - Background health monitoring
- 7 Command Handlers - Full Docker lifecycle control
- Extension Methods - AddDockerController(), AddDockerClient(), AddDockerControllerHandlers()
- Dashboard Extensions - Controller discovery and filtering
- Validators - Configuration and command validation
- Complete templates - Program.cs, appsettings.json, Dockerfile, README

🧪 TESTING:
- 56 new comprehensive tests (266 total tests passing)
- Configuration service tests (15 tests)
- Validator tests (41 tests)
- 100% test pass rate

📚 DOCUMENTATION:
- Complete Program.cs template with extensive comments
- Production-ready appsettings.json
- Sample modules.json
- Comprehensive README with 3 deployment options
- Dockerfile for containerized deployment

v1.0.0-beta8:
PHASE 11 CRITICAL UPDATES - See Docs/MigrationGuide-v1.0.0-beta8.md for complete details

🚨 BREAKING CHANGES:
- CorrelationId is now REQUIRED on FabricCommandRequest and FabricCommandResponse
(auto-generates if not set, but may cause compilation errors)
- FabricModuleState structure expanded with new optional properties

✨ NEW FEATURES:
1. Built-in Commands Always Available
- System.Ping, System.GetStatus, System.GetHealth work on ALL modules
- No ModuleCapabilities.CustomCommands required for built-in commands
- Command listener always enabled

2. Required Correlation IDs
- Guaranteed command response correlation
- Auto-generation if not explicitly set
- Full validation and Service Bus integration

3. Sticky Health Status
- Degraded/failed states persist for minimum display time
- Configurable durations (5min degraded, 10min failed by default)
- Health status history tracking (last 20 transitions)
- Operator acknowledgment support

4. Text Metrics Support
- Track error messages, logs, and configuration alongside numeric metrics
- Automatic aging and retention (1 hour default)
- Count limits (50 text metrics per module)
- 256 character key/value validation

📝 MIGRATION REQUIRED:
- Update all FabricCommandRequest/Response initializers to include CorrelationId
- Optionally implement text metrics in health reports
- Optionally configure sticky health settings in dashboard

📚 DOCUMENTATION:
- See Docs/MigrationGuide-v1.0.0-beta8.md for step-by-step migration
- 22 new comprehensive tests added
- Full API documentation in XML comments

v1.0.0-beta5:
- Corrected issue where module ID value was of a length that was not compatible with Service Bus entity naming rules.

v1.0.0-beta4:
- Automatic Service Bus entity provisioning during module and dashboard startup
- Topics and subscriptions are now created automatically if they don't exist
- Fail-fast behavior if provisioning fails (e.g., insufficient permissions)
- Requires management permissions on Service Bus connection string

v1.0.0-beta2:
- Simplified command registration using AddCustomCommandHandler()
- Automatic command discovery by dashboard
- Single point of command registration (no duplication)

v1.0.0-beta1:
- Initial beta release
- Module client integration with health reporting and command handling
- Dashboard client for monitoring and control
- Cross-communication prevention with fabric/environment/tenant isolation
- Automatic heartbeat and health reporting
- Comprehensive validation and security features