Core.Packages

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 16 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Core.Packages

![.NET](https://img.shields.io/badge/.NET-10.0-512BD4)
![C#](https://img.shields.io/badge/C%23-13-239120)
![License](https://img.shields.io/badge/license-MIT-blue)

A modular set of NuGet packages for building enterprise .NET applications following **Clean Architecture** principles. Provides ready-to-use infrastructure for data access, CQRS pipelines, security, event-driven messaging, and cross-cutting concerns.

## Packages

| Package | Description |
|---------|-------------|
| [Core.Persistence](#corepersistence) | Repository pattern (EF Core & Dapper), dynamic querying, pagination, file storage |
| [Core.Application](#coreapplication) | Result pattern, MediatR pipeline behaviors (validation, caching, authorization, logging, transactions) |
| [Core.Security](#coresecurity) | JWT authentication, refresh tokens, password hashing, OTP two-factor authentication |
| [Core.EventBus](#coreeventbus) | Event-driven messaging with RabbitMQ and Azure Service Bus |
| [Core.CrossCuttingConcerns](#corecrosscuttingconcerns) | Exception middleware, Serilog logging (File, Elasticsearch, MSSQL), ProblemDetails |

## Architecture

```mermaid
graph TD
    App["Core.Application"] --> CCC["Core.CrossCuttingConcerns"]
    App --> Per["Core.Persistence"]
    App --> Sec["Core.Security"]
    Sec --> Per
    Per --> CCC
    EB["Core.EventBus"]
```

### Design Patterns

- **Repository** -- Generic data access abstraction with EF Core and Dapper implementations
- **CQRS** -- Command/Query separation via MediatR
- **Pipeline** -- Cross-cutting behaviors injected into the MediatR pipeline
- **Result (Railway-Oriented)** -- Explicit success/failure propagation without exceptions
- **Factory** -- Event bus creation based on configuration
- **Strategy** -- Swappable file storage backends (local / Azure Blob)

## Installation

Install only the packages you need:

```bash
dotnet add package Core.Persistence
dotnet add package Core.Application
dotnet add package Core.Security
dotnet add package Core.EventBus
dotnet add package Core.CrossCuttingConcerns
```

---

## Core.Persistence

Data access layer providing the **Repository pattern** with both EF Core and Dapper, **dynamic querying**, **pagination**, and **file storage** abstractions.

### Base Entity

All entities inherit from `Entity<TId>` which includes automatic timestamp tracking and soft-delete support:

```csharp
public class Entity<TId> : IEntityTimestamps
{
    public TId Id { get; set; }
    public DateTime CreatedDate { get; set; }
    public DateTime? UpdatedDate { get; set; }
    public DateTime? DeletedDate { get; set; }
}
```

### Repository Pattern

#### Interfaces

Both `IAsyncRepository<TEntity, TEntityId>` and `IRepository<TEntity, TEntityId>` provide a full set of CRUD operations:

| Method | Description |
|--------|-------------|
| `GetAsync` / `Get` | Retrieve a single entity by predicate with optional includes |
| `GetListAsync` / `GetList` | Paginated list with filtering, ordering, and includes |
| `GetListByDynamicAsync` / `GetListByDynamic` | Paginated list using dynamic query filters |
| `WhereAsync` / `Where` | Returns `IQueryable<TEntity>` for further composition |
| `AnyAsync` / `Any` | Existence check |
| `AddAsync` / `Add` | Insert single entity |
| `AddRangeAsync` / `AddRange` | Bulk insert |
| `UpdateAsync` / `Update` | Update single entity |
| `UpdateRangeAsync` / `UpdateRange` | Bulk update |
| `DeleteAsync` / `Delete` | Soft-delete by default, permanent when specified |
| `DeleteRangeAsync` / `DeleteRange` | Bulk delete |
| `MigrateAsync` / `Migrate` | Apply database migrations |

#### EF Core Repository

```csharp
public class ProductRepository : EfRepositoryBase<Product, Guid, AppDbContext>, IProductRepository
{
    public ProductRepository(AppDbContext context) : base(context) { }
}
```

Features:
- Automatic `CreatedDate` / `UpdatedDate` timestamp management
- **Soft delete** with cascade support -- navigations with `DeleteBehavior.Cascade` or `ClientCascade` are automatically soft-deleted
- `AsNoTracking` support via `enableTracking` parameter
- `IgnoreQueryFilters` support via `withDeleted` parameter
- `IIncludableQueryable` support for eager loading

#### Dapper Repository

```csharp
public class ProductRepository : DapperRepositoryBase<Product, Guid>, IProductRepository
{
    public ProductRepository(IDbConnectionFactory connectionFactory)
        : base(connectionFactory, "Products") { }
}
```

Requires an `IDbConnectionFactory` implementation:

```csharp
public interface IDbConnectionFactory
{
    IDbConnection CreateConnection();
}
```

Features:
- Expression-to-SQL conversion for predicates
- Transaction support for batch operations
- Soft-delete with overridable `CascadeSoftDeleteAsync`
- Dynamic query support with parameterized SQL

### Dynamic Querying

Build dynamic filter and sort queries at runtime, suitable for grid/table UIs:

```csharp
var query = new DynamicQuery
{
    Filter = new Filter
    {
        Field = "Name",
        Operator = "contains",
        Value = "phone",
        Logic = "and",
        Filters = new[]
        {
            new Filter { Field = "Price", Operator = "gte", Value = "100" }
        }
    },
    Sort = new[] { new Sort("Price", "desc") }
};

Paginate<Product> result = await repository.GetListByDynamicAsync(query, index: 0, size: 10);
```

**Supported filter operators:**

| Operator | SQL Equivalent |
|----------|---------------|
| `eq` | `=` |
| `neq` | `!=` |
| `lt`, `lte` | `<`, `<=` |
| `gt`, `gte` | `>`, `>=` |
| `contains` | `LIKE '%value%'` |
| `startswith` | `LIKE 'value%'` |
| `endswith` | `LIKE '%value'` |
| `isnull` | `IS NULL` |
| `isnotnull` | `IS NOT NULL` |
| `doesnotcontain` | `NOT LIKE '%value%'` |

### Pagination

```csharp
Paginate<Product> page = await repository.GetListAsync(
    predicate: p => p.IsActive,
    orderBy: q => q.OrderByDescending(p => p.CreatedDate),
    index: 0,
    size: 20
);

// page.Items      -- current page items
// page.Count      -- total record count
// page.Pages      -- total page count
// page.HasNext    -- has next page
// page.HasPrevious -- has previous page
```

### File Storage

An abstraction over file operations with **Local** and **Azure Blob Storage** implementations.

#### Registration

```csharp
// Option 1: Local file storage
services.AddLocalFileStorage(basePath: "wwwroot/uploads");

// Option 2: Azure Blob Storage
services.AddAzureBlobFileStorage(
    connectionString: "DefaultEndpointsProtocol=https;...",
    containerName: "documents"
);

// Option 3: Configuration-based (reads from appsettings.json)
services.AddFileRepository(configuration);
```

Configuration via `appsettings.json`:

```json
{
  "FileStorage": {
    "StorageType": "Local",
    "BasePath": "wwwroot/Documents",
    "EnsureDirectoryExists": true,
    "AzureConnectionString": "",
    "AzureContainerName": ""
  }
}
```

#### Usage

```csharp
public class DocumentService(IFileRepository fileRepository)
{
    public async Task<FileUploadResult> UploadAsync(Stream stream, string fileName)
    {
        return await fileRepository.UploadAsync(stream, fileName, DocumentTypeEnum.PDF);
    }

public async Task<FileDownloadResult> DownloadAsync(string path)
    {
        return await fileRepository.DownloadAsync(path);
    }
}
```

**Supported document types:** JPG, JPEG, PNG, PDF, XML

---

## Core.Application

Application layer built on **MediatR** providing a **Result pattern** for railway-oriented programming and a rich set of **pipeline behaviors**.

### Result Pattern

Explicit success/failure handling without relying on exceptions for control flow.

#### Creating Results

```csharp
// Success
var success = Result<Product>.Success(product);
var created = Result<Product>.SuccessAsCreated(product, $"/api/products/{product.Id}");

// Failure
var notFound = Result<Product>.NotFound("Product not found");
var validation = Result<Product>.ValidationFailure("Name is required");
var forbidden = Result<Product>.Forbidden("Access denied");
var conflict = Result<Product>.Conflict("Product already exists");
```

#### Railway-Oriented Methods

```csharp
Result<OrderDto> result = await Result<Product>.Success(product)
    .Ensure(p => p.Stock > 0, Error.Failure("Out of stock", "STOCK_ERROR"))
    .Map(p => new OrderDto(p.Id, p.Name, p.Price))
    .Tap(dto => logger.LogInformation("Order created for {Name}", dto.Name))
    .OnFailure(errors => logger.LogWarning("Failed: {Errors}", errors));
```

| Method | Description |
|--------|-------------|
| `Map` | Transform the value if successful |
| `Bind` | Chain another Result-returning operation |
| `Match` | Pattern-match on success/failure |
| `Ensure` | Validate a condition, fail if false |
| `Tap` | Execute a side effect on success |
| `OnFailure` | Execute a side effect on failure |
| `Combine` | Merge multiple results |
| `Try` / `TryAsync` | Wrap an operation in try-catch returning Result |

#### Error Types

```csharp
public enum ErrorType
{
    Failure,      // 400 Bad Request
    Validation,   // 422 Unprocessable Entity
    NotFound,     // 404 Not Found
    Unauthorized, // 401 Unauthorized
    Forbidden,    // 403 Forbidden
    Conflict      // 409 Conflict
}
```

Each error type automatically maps to the appropriate HTTP status code and produces a `ProblemDetails` response.

#### Implicit Conversions

```csharp
// Value automatically wraps in Success
Result<int> result = 42;

// Error automatically wraps in Failure
Result<int> result = Error.NotFound("Item not found");
```

#### MediatR Integration

Use `IRequestByResult` and `IRequestByResult<T>` as MediatR request interfaces:

```csharp
public record GetProductQuery(Guid Id) : IRequestByResult<ProductDto>;

public class GetProductHandler : IRequestHandler<GetProductQuery, Result<ProductDto>>
{
    public async Task<Result<ProductDto>> Handle(GetProductQuery request, CancellationToken ct)
    {
        var product = await repository.GetAsync(p => p.Id == request.Id);
        if (product is null)
            return Result<ProductDto>.NotFound("Product not found");

return Result<ProductDto>.Success(mapper.Map<ProductDto>(product));
    }
}
```

#### Refit API Exception Handling

Convert Refit `ApiException` responses into Result objects:

```csharp
try
{
    var data = await refitClient.GetDataAsync();
    return Result<Data>.Success(data);
}
catch (ApiException ex)
{
    return ResultExtensions.ErrorFromApiException<Data>(ex);
}
```

### Pipeline Behaviors

MediatR pipeline behaviors are activated by implementing marker interfaces on your request classes.

#### Validation (`RequestValidationBehavior`)

Automatically validates requests using **FluentValidation**. No marker interface needed -- any request with a registered `IValidator<TRequest>` is validated.

```csharp
public class CreateProductCommand : IRequest<Result<Guid>>
{
    public string Name { get; set; }
    public decimal Price { get; set; }
}

public class CreateProductValidator : AbstractValidator<CreateProductCommand>
{
    public CreateProductValidator()
    {
        RuleFor(x => x.Name).NotEmpty().MaximumLength(200);
        RuleFor(x => x.Price).GreaterThan(0);
    }
}
```

Throws `ValidationException` with grouped property errors on failure.

#### Caching (`CachingBehavior` / `CacheRemovingBehavior`)

Distributed cache integration with cache groups.

```csharp
// Cacheable query
public record GetProductsQuery : IRequest<Paginate<ProductDto>>, ICachableRequest
{
    public string CacheKey => "products-list";
    public bool BypassCache => false;
    public string? CacheGroupKey => "products";
    public TimeSpan? SlidingExpiration => null; // uses default from CacheSettings
}

// Cache-invalidating command
public record CreateProductCommand : IRequest<Result<Guid>>, ICacheRemoverRequest
{
    public string? CacheKey => null;
    public bool BypassCache => false;
    public string? CacheGroupKey => "products"; // invalidates entire group
}
```

Configuration via `appsettings.json`:

```json
{
  "CacheSettings": {
    "SlidingExpiration": 2
  }
}
```

#### Authorization (`AuthorizationBehavior`)

Role-based authorization using JWT claims.

```csharp
public record DeleteProductCommand(Guid Id) : IRequest<Result>, ISecuredRequest
{
    public string[] Roles => new[] { "Admin", "ProductManager" };
}
```

The `Admin` role always bypasses role checks (defined in `GeneralOperationClaims.Admin`).

#### Logging (`LoggingBehavior`)

Logs request details including type, parameters, and the current user.

```csharp
public record GetProductQuery(Guid Id) : IRequest<ProductDto>, ILoggableRequest;
```

#### Exception Handling (`ExceptionHandlingBehavior`)

Catches and logs exceptions thrown during request handling.

```csharp
public record ProcessOrderCommand : IRequest<Result>, IExceptionalRequest;
```

#### Transaction (`TransactionScopeBehavior`)

Wraps the request handler in a `TransactionScope`.

```csharp
public record TransferFundsCommand : IRequest<Result>, ITransactionalRequest;
```

### Requests & Responses

```csharp
// Pagination request
public class PageRequest
{
    public int PageIndex { get; set; }
    public int PageSize { get; set; }
}

// Paginated response
public class GetListResponse<T> : BasePageableModel
{
    public IList<T> Items { get; set; }
}
```

---

## Core.Security

Authentication and authorization infrastructure including **JWT tokens**, **refresh tokens**, **password hashing**, and **OTP two-factor authentication**.

### Service Registration

```csharp
services.AddSecurityServices();
```

Registers:
- `ITokenHelper` -> `JwtHelper` (Scoped)
- `IOtpAuthenticatorHelper` -> `OtpNetOtpAuthenticatorHelper` (Scoped)

### JWT Authentication

#### Configuration

Add to `appsettings.json`:

```json
{
  "TokenOptions": {
    "Audience": "your-audience",
    "Issuer": "your-issuer",
    "AccessTokenExpiration": 60,
    "SecurityKey": "your-very-long-secret-key-minimum-64-characters-for-hmac-sha512",
    "RefreshTokenTTL": 7
  }
}
```

#### Token Creation

```csharp
public class AuthService(ITokenHelper tokenHelper)
{
    public AccessToken CreateToken(User user, IList<OperationClaim> claims)
    {
        // Returns { Token: "eyJ...", Expiration: DateTime }
        return tokenHelper.CreateToken(user, claims);
    }

public RefreshToken CreateRefreshToken(User user, string ipAddress)
    {
        return tokenHelper.CreateRefreshToken(user, ipAddress);
    }
}
```

JWT claims automatically include: `NameIdentifier` (user ID), `Email`, `Name` (first + last), and `Role` (from operation claims).

### Password Hashing

HMAC-SHA512 based password hashing:

```csharp
// Create hash
HashingHelper.CreatePasswordHash("password123", out byte[] hash, out byte[] salt);

// Verify
bool isValid = HashingHelper.VerifyPasswordHash("password123", hash, salt);
```

### OTP Two-Factor Authentication

```csharp
public class TwoFactorService(IOtpAuthenticatorHelper otpHelper)
{
    public async Task<byte[]> GenerateSecretKey()
    {
        return await otpHelper.GenerateSecretKey();
    }

public async Task<string> GetSetupCode(byte[] secretKey)
    {
        return await otpHelper.ConvertSecretKeyToString(secretKey);
    }

public async Task<bool> VerifyCode(byte[] secretKey, string code)
    {
        return await otpHelper.VerifyCode(secretKey, code);
    }
}
```

### Security Entities

| Entity | Description |
|--------|-------------|
| `User` | User with email, password hash/salt, authenticator type |
| `OperationClaim` | Named role/permission |
| `UserOperationClaim` | Many-to-many join between User and OperationClaim |
| `RefreshToken` | Refresh token with expiry, IP tracking, revocation support |
| `OtpAuthenticator` | OTP secret key and verification status |
| `EmailAuthenticator` | Email-based 2FA activation key |

All entities use `Guid` as primary key and inherit from `Entity<Guid>`.

### Claims Extensions

```csharp
// Read claims from ClaimsPrincipal
List<string>? roles = httpContext.User.ClaimRoles();
int userId = httpContext.User.GetUserId();
```

---

## Core.EventBus

Event-driven messaging abstraction with **RabbitMQ** and **Azure Service Bus** implementations, featuring retry policies via Polly.

### Event Bus Factory

```csharp
services.AddSingleton<IEventBus>(sp =>
{
    return EventBusFactory.Create(new EventBusConfig
    {
        ConnectionRetryCount = 5,
        EventBusType = EventBusType.RabbitMQ,
        SubscriberClientAppName = "OrderService",
        DefaultTopicName = "CoreEventBus",
        EventNameSuffix = "IntegrationEvent",
        Connection = new ConnectionFactory
        {
            HostName = "localhost",
            Port = 5672,
            UserName = "guest",
            Password = "guest"
        }
    }, sp);
});
```

For Azure Service Bus:

```csharp
EventBusFactory.Create(new EventBusConfig
{
    EventBusType = EventBusType.AzureServiceBus,
    EventBusConnectionString = "Endpoint=sb://...",
    SubscriberClientAppName = "OrderService",
    DefaultTopicName = "CoreEventBus"
}, serviceProvider);
```

### Defining Events

```csharp
public class OrderCreatedIntegrationEvent : IntegrationEvent
{
    public Guid OrderId { get; set; }
    public decimal TotalAmount { get; set; }

public OrderCreatedIntegrationEvent(Guid orderId, decimal totalAmount)
    {
        OrderId = orderId;
        TotalAmount = totalAmount;
    }
}
```

### Event Handlers

```csharp
public class OrderCreatedHandler : IIntegrationEventHandler<OrderCreatedIntegrationEvent>
{
    public async Task Handle(OrderCreatedIntegrationEvent @event)
    {
        // Process the event
        Console.WriteLine($"Order created: {@event.OrderId}, Amount: {@event.TotalAmount}");
    }
}
```

### Publishing Events

```csharp
// Synchronous
eventBus.Publish(new OrderCreatedIntegrationEvent(orderId, 99.99m));

// Asynchronous
await eventBus.PublishAsync(new OrderCreatedIntegrationEvent(orderId, 99.99m));
```

### Subscribing to Events

```csharp
eventBus.Subscribe<OrderCreatedIntegrationEvent, OrderCreatedHandler>();

// or async
await eventBus.SubscribeAsync<OrderCreatedIntegrationEvent, OrderCreatedHandler>();
```

### Configuration Options

| Property | Default | Description |
|----------|---------|-------------|
| `ConnectionRetryCount` | 5 | Number of connection retry attempts |
| `DefaultTopicName` | "CoreEventBus" | Exchange (RabbitMQ) or Topic (Azure SB) name |
| `EventBusConnectionString` | "" | Connection string (Azure SB) |
| `SubscriberClientAppName` | "" | Prefix for subscription/queue names |
| `EventNamePrefix` | "" | Prefix to trim from event names |
| `EventNameSuffix` | "IntegrationEvent" | Suffix to trim from event names |
| `EventBusType` | RabbitMQ | `RabbitMQ` or `AzureServiceBus` |
| `Connection` | null | RabbitMQ `ConnectionFactory` settings |

### Features

- **Persistent connections** with automatic reconnection (RabbitMQ)
- **Retry policies** via Polly with exponential backoff
- **In-memory subscription manager** for handler resolution
- **Automatic topic/subscription creation** (Azure Service Bus)
- **Message correlation filtering** for Azure Service Bus subscriptions
- Async and sync APIs for publishing, subscribing, and unsubscribing

---

## Core.CrossCuttingConcerns

Infrastructure for **global exception handling**, **structured logging** with Serilog, and **ProblemDetails** HTTP responses.

### Exception Middleware

```csharp
app.ConfigureCustomExceptionMiddleware();
```

The middleware catches all unhandled exceptions, logs them via `LoggerServiceBase`, and returns structured `ProblemDetails` JSON responses.

### Custom Exception Types

| Exception | HTTP Status | ProblemDetails Title |
|-----------|-------------|---------------------|
| `BusinessException` | 400 Bad Request | "Rule Violation" |
| `ValidationException` | 400 Bad Request | "Validation error(s)" |
| `AuthorizationException` | (handled by pipeline) | -- |
| `FileValidationException` | 400 Bad Request | "File Validation Error" |
| `FileStorageException` | 500 Internal Server Error | "File Storage Error" |
| Other `Exception` | 500 Internal Server Error | "Internal Server Error" |

#### Throwing Business Exceptions

```csharp
public class ProductBusinessRules
{
    public void EnsureProductNameIsUnique(string name, bool exists)
    {
        if (exists)
            throw new BusinessException("Product name already exists.");
    }
}
```

### Serilog Logging

Three built-in logger implementations, all inheriting from `LoggerServiceBase`:

#### File Logger

```csharp
services.AddSingleton<LoggerServiceBase, FileLogger>();
```

```json
{
  "SeriLogConfigurations": {
    "FileLogConfiguration": {
      "FolderPath": "/logs/app"
    }
  }
}
```

#### Elasticsearch Logger

```csharp
services.AddSingleton<LoggerServiceBase, ElasticSearchLogger>();
```

```json
{
  "SeriLogConfigurations": {
    "ElasticSearchConfiguration": {
      "ConnectionUrl": "http://localhost:9200",
      "IndexFormat": "app-logs-{0:yyyy.MM.dd}",
      "AutoRegisterTemplate": true
    }
  }
}
```

#### MS SQL Logger

```csharp
services.AddSingleton<LoggerServiceBase, MsSqlLogger>();
```

```json
{
  "SeriLogConfigurations": {
    "MsSqlConfiguration": {
      "ConnectionString": "Server=localhost;Database=Logs;...",
      "TableName": "Logs",
      "AutoCreateSqlTable": true
    }
  }
}
```

#### Logger API

All loggers expose the same methods via `LoggerServiceBase`:

```csharp
loggerService.Verbose("Detailed trace information");
loggerService.Debug("Debug information");
loggerService.Info("Informational message");
loggerService.Warn("Warning message");
loggerService.Error("Error message");
loggerService.Fatal("Fatal error message");
```

---

## Full Configuration Example

A complete `appsettings.json` covering all packages:

```json
{
  "TokenOptions": {
    "Audience": "myapp.com",
    "Issuer": "myapp.com",
    "AccessTokenExpiration": 60,
    "SecurityKey": "my-very-long-secret-key-that-is-at-least-64-characters-long-for-hmac-sha512-signing",
    "RefreshTokenTTL": 7
  },
  "CacheSettings": {
    "SlidingExpiration": 2
  },
  "FileStorage": {
    "StorageType": "Local",
    "BasePath": "wwwroot/Documents",
    "EnsureDirectoryExists": true
  },
  "SeriLogConfigurations": {
    "FileLogConfiguration": {
      "FolderPath": "/logs/app"
    },
    "MsSqlConfiguration": {
      "ConnectionString": "Server=.;Database=Logs;Trusted_Connection=True;",
      "TableName": "Logs",
      "AutoCreateSqlTable": true
    },
    "ElasticSearchConfiguration": {
      "ConnectionUrl": "http://localhost:9200",
      "IndexFormat": "app-logs-{0:yyyy.MM.dd}",
      "AutoRegisterTemplate": true
    }
  }
}
```

## Dependencies

| Package | Key Dependencies |
|---------|-----------------|
| Core.Persistence | EF Core 10.0, Dapper 2.1, Azure.Storage.Blobs 12.27, System.Linq.Dynamic.Core 1.7 |
| Core.Application | MediatR 14.0, FluentValidation 12.1, Refit 10.0 |
| Core.Security | System.IdentityModel.Tokens.Jwt 8.16, Otp.NET 1.4 |
| Core.EventBus | RabbitMQ.Client 7.2, Azure.Messaging.ServiceBus 7.20, Polly 8.6 |
| Core.CrossCuttingConcerns | Serilog 4.3, Serilog.Sinks.File 7.0, Serilog.Sinks.Elasticsearch 10.0, Serilog.Sinks.MSSqlServer 9.0 |

## Requirements

- **.NET 10.0** or later
- **C# 13** or later

## Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

## License

This project is licensed under the [MIT License](LICENSE).

Core.Packages

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README