Libraries Catalog

This document catalogs the ConnectSoft.Extensions.* libraries and other reusable libraries available for use in Factory-generated systems and by human developers. It is written for developers and architects selecting libraries for their projects.

ConnectSoft maintains a comprehensive set of reusable libraries that provide common functionality across all generated systems. These libraries follow ConnectSoft's architectural principles, are designed for multi-tenant SaaS applications, and integrate seamlessly with Factory-generated code.

Tip

Use ConnectSoft.Extensions.* libraries for common functionality. They're battle-tested, multi-tenant-safe, and integrate seamlessly with Factory-generated code. All libraries follow semantic versioning and are compatible with Factory-generated services.

Available Libraries

ConnectSoft provides a curated set of reusable libraries published as NuGet packages. Each library is designed to encapsulate a specific cross-cutting concern or foundational capability for modern .NET applications.

All packages are compatible with .NET 8+ and align with best practices in microservice, DDD, and configuration-driven environments.

1. ConnectSoft.Extensions

• Purpose: Utility extensions for native .NET types (string, int, DateTime, etc.) and shared base types.
• Key Features:
  • string.ToSlug(), int.IsEven(), DateTime.IsWeekend()
  • IEnumerable<T>.IsNullOrEmpty()
  • Base exception for domain logic: DomainModelException
• Use Cases: Utility libraries, shared code, microservices
• NuGet: View Package
• Status: 🟢 Stable

2. ConnectSoft.Extensions.DataAnnotations

• Purpose: Adds missing validation functionality to .NET's DataAnnotations system.
• Key Features:
  • NotDefaultAttribute — works on any struct (Guid, DateTime, int, etc.)
  • Null-safe: integrates cleanly with [Required] if needed
  • Supports IOptions<T>, domain models, and DTOs
• Use Cases: Domain validation, configuration binding, API model validation
• NuGet: View Package
• Status: 🟢 Stable

3. ConnectSoft.Extensions.DatabaseModel

• Purpose: Provides an abstraction layer for managing and provisioning database instances.
• Key Features:
  • IDatabaseHelper interface for cross-database operations: creation, schema setup, SQL execution
  • Core interface, no database-specific logic
• Use Cases: Infrastructure initialization, CI/CD provisioning, tenant setup
• NuGet: View Package
• Status: 🟢 Stable

Implementors

• ConnectSoft.Extensions.DatabaseModel.SqlServer - SQL Server implementation of IDatabaseHelper using SqlConnection.
• ConnectSoft.Extensions.DatabaseModel.PostgreSql - PostgreSQL implementation with NpgsqlConnection.
• ConnectSoft.Extensions.DatabaseModel.MySql - MySQL implementation using MySqlConnector.

4. ConnectSoft.Extensions.Globalization

• Purpose: Provides utilities and calendar extensions for working with the Jewish calendar and Hebrew characters.
• Key Features:
  • Gregorian ⇄ Jewish date conversions
  • Jewish holiday recognition
  • Leap year and day-of-week calculations
  • Hebrew character classification (letters, finals, etc.)
• Use Cases: Localization engines, religious calendar support, Hebrew text analysis
• NuGet: View Package
• Status: 🟢 Stable

5. ConnectSoft.Extensions.MessagingModel

A messaging-agnostic abstraction that defines base interfaces for event-driven communication patterns.

• Purpose: Acts as the foundation for messaging libraries, providing core contracts like ICommand, IEvent, and IEventBus.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.MessagingModel
• Source: Repository
• Status: 🟢 Stable
• Implementations:
  • ✅ ConnectSoft.Extensions.MessagingModel.NServiceBus
  • ✅ ConnectSoft.Extensions.MessagingModel.MassTransit

6. ConnectSoft.Extensions.MessagingModel.MassTransit

MassTransit-based implementation of the ConnectSoft messaging model abstraction.

• Purpose: Bridges IEventBus with MassTransit APIs for command and event messaging.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.MessagingModel.MassTransit
• Source: Repository

7. ConnectSoft.ExtensionsMessagingModel.NServiceBus

NServiceBus-based implementation of the ConnectSoft messaging model abstraction.

• Purpose: Bridges IEventBus with NServiceBus APIs; includes extra utilities like DI extensions and header propagation.
• Framework: .NET 8+
• NuGet: ConnectSoft.ExtensionsMessagingModel.NServiceBus
• Source: Repository

8. ConnectSoft.Extensions.EntityModel

Comprehensive modeling base for Domain-Driven Design (DDD) in .NET applications.

• Purpose: Provides base contracts for entities, value objects, aggregate roots, and rich enumerations. Enables consistent modeling patterns across bounded contexts.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.EntityModel
• Source: Repository

9. ConnectSoft.Extensions.DomainModel

Foundation for implementing Domain Services and Use Case handlers based on Domain-Driven Design (DDD), Clean Architecture, and Hexagonal Architecture principles.

• Purpose: Supports separation of concerns by defining contracts for IDomainService and IUseCase<TInput, TOutput>; enables maintainable, testable application cores.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.DomainModel
• Source: Repository

10. ConnectSoft.Extensions.DomainModel.Impl

🛠️ Under Construction

Implementation-ready shell for domain modeling components (IDomainService, IUseCase, etc.) defined in ConnectSoft.Extensions.DomainModel.

• Purpose: Serves as the starting point for internal or shared domain service implementations that extend base contracts.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.DomainModel.Impl
• Source: Repository

11. ConnectSoft.Extensions.Transactions

Lightweight abstraction for managing transactional boundaries in a clean and testable manner.

• Purpose: Centralizes ITransaction and TransactionScopeTransaction handling in a consistent interface across persistence strategies.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.Transactions
• Source: Repository

12. ConnectSoft.Extensions.PersistenceModel

Data source–agnostic abstraction for persistence patterns such as repository, unit of work, specifications, and queries. Designed for use with DDD and clean architecture approaches.

• Purpose: Provides consistent and testable data access APIs over any backing store. Built on top of ConnectSoft.Extensions.EntityModel.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.PersistenceModel
• Source: Repository

13. ConnectSoft.Extensions.PersistenceModel.DependencyInjection

Dependency injection extensions for the ConnectSoft persistence model.

• Purpose: Provides Microsoft.Extensions.DependencyInjection–based implementations of key infrastructure components:
  • IQueryBuilder → MicrosoftQueryBuilder
  • ISpecificationLocator → MicrosoftSpecificationLocator
  • Designed to seamlessly resolve queries and specifications for repositories via standard .NET DI.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.PersistenceModel.DependencyInjection
• Source: Repository

14. ConnectSoft.Extensions.PersistenceModel.NHibernate

NHibernate-based implementation of the ConnectSoft persistence model abstraction.

• Purpose: Enables full repository, unit of work, query, and specification patterns using NHibernate; includes logging, transient tracking, enumeration mapping, and DI support.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.PersistenceModel.NHibernate
• Source: Repository

15. ConnectSoft.Extensions.ServiceModel

Communication-agnostic base library for structured service contracts, fault handling, and interoperable message definitions.

• Purpose: Defines fault contracts, service/message wrappers, and metadata for use across WCF, REST, gRPC, CoreWCF, Orleans, and Service Fabric.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.ServiceModel
• Source: Repository

16. ConnectSoft.Text.Json

Extension library built on System.Text.Json to enhance enum serialization, formatting, and deserialization behaviors.

• Purpose: Supports [EnumMember(Value = "...")], improves compatibility with external APIs, and simplifies JSON configuration.
• Framework: .NET 8+
• NuGet: ConnectSoft.Text.Json
• Source: Repository

17. ConnectSoft.Extensions.Http.OAuth2

Extensible, DI-based library for OAuth 2.0 token acquisition and management in .NET 8+.

• Purpose: Supports multiple grant types (client credentials, password, refresh), named clients, token caching, ID token validation, and test automation with WireMock.
• Framework: .NET 8+
• NuGet: ConnectSoft.Extensions.Http.OAuth2
• Source: Repository

18. ConnectSoft.Net.Http

Extension utilities for working with HttpClient in .NET.

• Purpose: Adds missing methods like DeleteAsJsonAsync, and includes SubdirectoryHandler for reverse proxy URL rewriting — useful in gRPC or IIS-hosted services.
• Framework: .NET 8+
• NuGet: ConnectSoft.Net.Http
• Source: Repository

Library Families (Summary)

For quick reference, here are the main library families:

Library / Namespace	Purpose	Typical Consumers
ConnectSoft.Extensions	Utility extensions for native .NET types	All projects
ConnectSoft.Extensions.DataAnnotations	Enhanced validation attributes	Domain models, DTOs
ConnectSoft.Extensions.DatabaseModel	Database provisioning abstraction	Infrastructure, CI/CD
ConnectSoft.Extensions.Globalization	Jewish calendar and Hebrew text utilities	Localization engines
ConnectSoft.Extensions.MessagingModel	Messaging abstractions (MassTransit, NServiceBus)	Event-driven services
ConnectSoft.Extensions.EntityModel	DDD entity and value object base classes	Domain models
ConnectSoft.Extensions.DomainModel	Domain services and use case contracts	Application layer
ConnectSoft.Extensions.Transactions	Transaction management abstraction	Persistence layer
ConnectSoft.Extensions.PersistenceModel	Repository and specification patterns	Data access layer
ConnectSoft.Extensions.ServiceModel	Service contract definitions	API layer
ConnectSoft.Text.Json	Enhanced JSON serialization	All projects
ConnectSoft.Extensions.Http.OAuth2	OAuth2 token management	API clients
ConnectSoft.Net.Http	HttpClient extensions	API clients

Coming Soon

• ConnectSoft.Extensions.ServiceModel.Grpc
• ConnectSoft.Extensions.ServiceModel.Grpc.Client

Stay tuned for more reusable and production-ready components.

Common Usage Patterns

Dependency Injection Registration

Pattern: Register libraries in Program.cs or Startup.cs:

using ConnectSoft.Extensions.Logging;
using ConnectSoft.Extensions.OpenTelemetry;
using ConnectSoft.Extensions.Messaging;
using ConnectSoft.Extensions.Identity;

var builder = WebApplication.CreateBuilder(args);

// Register logging with correlation ID support
builder.Services.AddConnectSoftLogging(options =>
{
    options.EnableCorrelationId = true;
    options.LogLevel = LogLevel.Information;
});

// Register OpenTelemetry tracing and metrics
builder.Services.AddConnectSoftOpenTelemetry(options =>
{
    options.ServiceName = "InvoiceService";
    options.EnableTracing = true;
    options.EnableMetrics = true;
});

// Register messaging (Service Bus)
builder.Services.AddConnectSoftMessaging(options =>
{
    options.ConnectionString = builder.Configuration["ServiceBus:ConnectionString"];
    options.EnableEventPublishing = true;
});

// Register identity and tenant context
builder.Services.AddConnectSoftIdentity(options =>
{
    options.TenantContextHeader = "X-Tenant-Id";
    options.EnableTenantIsolation = true;
});

var app = builder.Build();

Using Libraries in Generated Services

Pattern: Use libraries in use cases, repositories, and controllers:

using ConnectSoft.Extensions.Logging;
using ConnectSoft.Extensions.Messaging;
using ConnectSoft.Extensions.Identity;

public class CreateInvoiceUseCase
{
    private readonly ILogger<CreateInvoiceUseCase> _logger;
    private readonly IEventPublisher _eventPublisher;
    private readonly ITenantContext _tenantContext;

    public CreateInvoiceUseCase(
        ILogger<CreateInvoiceUseCase> logger,
        IEventPublisher eventPublisher,
        ITenantContext tenantContext)
    {
        _logger = logger;
        _eventPublisher = eventPublisher;
        _tenantContext = tenantContext;
    }

    public async Task<InvoiceDto> ExecuteAsync(CreateInvoiceRequest request)
    {
        // Log with correlation ID (automatically included)
        _logger.LogInformation("Creating invoice for tenant {TenantId}", 
            _tenantContext.CurrentTenantId);

        // Create invoice (domain logic)
        var invoice = new Invoice(...);

        // Publish domain event
        await _eventPublisher.PublishAsync(new InvoiceCreatedEvent
        {
            InvoiceId = invoice.Id,
            TenantId = _tenantContext.CurrentTenantId
        });

        return InvoiceMapper.ToDto(invoice);
    }
}

HTTP Client with Retry and Circuit Breaker

Pattern: Use HTTP extension for resilient external API calls:

using ConnectSoft.Extensions.Http;

// Register HTTP client with retry and circuit breaker
builder.Services.AddConnectSoftHttpClient<IPaymentGatewayClient, PaymentGatewayClient>(options =>
{
    options.BaseAddress = new Uri("https://api.paymentgateway.com");
    options.RetryPolicy = RetryPolicy.ExponentialBackoff(maxRetries: 3);
    options.CircuitBreaker = new CircuitBreakerOptions
    {
        FailureThreshold = 5,
        DurationOfBreak = TimeSpan.FromSeconds(30)
    };
});

// Use in service
public class PaymentService
{
    private readonly IPaymentGatewayClient _paymentClient;

    public async Task<PaymentResult> ProcessPaymentAsync(PaymentRequest request)
    {
        // Automatic retry and circuit breaker handling
        var response = await _paymentClient.ProcessPaymentAsync(request);
        return response;
    }
}

Audit Logging

Pattern: Use audit extension for compliance logging:

using ConnectSoft.Extensions.Audit;

public class InvoiceService
{
    private readonly IAuditLogger _auditLogger;

    public async Task CreateInvoiceAsync(CreateInvoiceRequest request)
    {
        // Create invoice
        var invoice = new Invoice(...);

        // Log audit event
        await _auditLogger.LogAsync(new AuditEvent
        {
            Action = "InvoiceCreated",
            EntityType = "Invoice",
            EntityId = invoice.Id.ToString(),
            TenantId = _tenantContext.CurrentTenantId,
            UserId = _userContext.CurrentUserId,
            Timestamp = DateTime.UtcNow,
            Details = new { Amount = invoice.Amount, Status = invoice.Status }
        });
    }
}

Versioning and Compatibility

Semantic Versioning

All ConnectSoft.Extensions.* libraries follow semantic versioning (SemVer):

• Major version - Breaking changes (e.g., 2.0.0)
• Minor version - New features, backward compatible (e.g., 1.1.0)
• Patch version - Bug fixes, backward compatible (e.g., 1.0.1)

Factory Version Pinning

The Factory pins library versions in generated projects:

• Generated services reference specific library versions (e.g., ConnectSoft.Extensions.Logging version 1.2.3)
• Version compatibility - Factory ensures compatible versions across all libraries
• Update policy - Factory updates library versions in new generations, existing services can update manually

Compatibility Policy

Important

Generated services should not downgrade library versions below those supported by the Factory. Upgrading to newer minor/patch versions is safe and recommended. Major version upgrades require careful testing and may require code changes.

Compatibility Rules:

• Same major version - Minor and patch updates are safe
• Different major version - Requires code review and testing
• Factory support - Factory supports latest 2 major versions of each library

Version Update Example

Scenario: Update ConnectSoft.Extensions.Logging from 1.2.3 to 1.3.0.

Process: 1. Update package reference in .csproj:

<PackageReference Include="ConnectSoft.Extensions.Logging" Version="1.3.0" />

2. Run dotnet restore and dotnet build 3. Test service to ensure compatibility 4. Deploy updated service

Breaking Change: If updating to 2.0.0, review breaking changes in library changelog and update code accordingly.

Example Integration

Here's a complete example showing a microservice using multiple libraries:

// Program.cs - Service registration
using ConnectSoft.Extensions.Logging;
using ConnectSoft.Extensions.OpenTelemetry;
using ConnectSoft.Extensions.Messaging;
using ConnectSoft.Extensions.Identity;
using ConnectSoft.Extensions.Audit;

var builder = WebApplication.CreateBuilder(args);

// Register all extensions
builder.Services.AddConnectSoftLogging();
builder.Services.AddConnectSoftOpenTelemetry(options =>
{
    options.ServiceName = "InvoiceService";
});
builder.Services.AddConnectSoftMessaging(options =>
{
    options.ConnectionString = builder.Configuration["ServiceBus:ConnectionString"];
});
builder.Services.AddConnectSoftIdentity();
builder.Services.AddConnectSoftAudit();

// Register application services
builder.Services.AddScoped<ICreateInvoiceUseCase, CreateInvoiceUseCase>();

var app = builder.Build();

// Use in controller
app.MapPost("/invoices", async (CreateInvoiceRequest request, 
    ICreateInvoiceUseCase useCase) =>
{
    return await useCase.ExecuteAsync(request);
});

app.Run();

// UseCase - Using libraries
public class CreateInvoiceUseCase : ICreateInvoiceUseCase
{
    private readonly ILogger<CreateInvoiceUseCase> _logger;
    private readonly IEventPublisher _eventPublisher;
    private readonly ITenantContext _tenantContext;
    private readonly IAuditLogger _auditLogger;

    public CreateInvoiceUseCase(
        ILogger<CreateInvoiceUseCase> logger,
        IEventPublisher eventPublisher,
        ITenantContext tenantContext,
        IAuditLogger auditLogger)
    {
        _logger = logger;
        _eventPublisher = eventPublisher;
        _tenantContext = tenantContext;
        _auditLogger = auditLogger;
    }

    public async Task<InvoiceDto> ExecuteAsync(CreateInvoiceRequest request)
    {
        // Logging with correlation ID
        _logger.LogInformation("Creating invoice for tenant {TenantId}", 
            _tenantContext.CurrentTenantId);

        // Create invoice (domain logic)
        var invoice = new Invoice(request.Amount, request.Description);

        // Publish domain event
        await _eventPublisher.PublishAsync(new InvoiceCreatedEvent
        {
            InvoiceId = invoice.Id,
            TenantId = _tenantContext.CurrentTenantId
        });

        // Audit log
        await _auditLogger.LogAsync(new AuditEvent
        {
            Action = "InvoiceCreated",
            EntityId = invoice.Id.ToString(),
            TenantId = _tenantContext.CurrentTenantId
        });

        return InvoiceMapper.ToDto(invoice);
    }
}

Key Points: - All libraries registered in Program.cs - Libraries used throughout the service (logging, messaging, identity, audit) - Correlation IDs, tenant context, and audit logging work automatically - OpenTelemetry tracing includes all operations

Related Documents

• Templates Overview - Overview of templates and libraries
• Microservice Template - How templates use libraries
• Technology Stack - Technologies and frameworks
• Factory Overview - How the Factory uses libraries