Flexbase 10

This page contains self-contained upgrade instructions for FlexBase 10 dev builds.

Upgrade Builds

• 10.0.0-Dev-Build026 (January 2026)

• FlexBase 9 to 10 Migration Steps

---

10.0.0-Dev-Build026

What This Upgrade Changes

• Consolidates exception handling into FlexExceptionFilter + UseFlexExceptionHandler()

• Adds optional rate limiting support

• Adds optional OpenTelemetry configuration

• Standardizes EF Core feature configuration (Audit Trail, Soft Delete, Async Query Executor)

• Updates generated queries/handlers to use true async (*AsyncFlex)

• Adds optional Subscriber Idempotency configuration

---

Upgrade Steps

Step 1: Exception Handling Improvements

What to change

1. Replace FlexStandardExceptionFilter with FlexExceptionFilter in your MVC filter registration.

2. Add app.UseFlexExceptionHandler() after CORS.

Example

builder.Services.AddControllers(config =>
{
    // ... other config
    config.Filters.Add<FlexStandardResponseFilter>();
    config.Filters.Add<FlexExceptionFilter>();
});

var app = builder.Build();

app.UseCors(MyAllowSpecificOrigins);
app.UseFlexExceptionHandler();

---

Step 2: Rate Limiting Support (Optional)

What to change

If you want rate limiting:

// builder.Services.AddFlexRateLimiting(builder.Configuration);

var app = builder.Build();

// app.UseFlexRateLimiting();

Keep it commented out if you don't need rate limiting.

---

Step 3: OpenTelemetry Configuration (Optional)

What to change

If you want OpenTelemetry, wire it from your WebAPI startup (exact method names vary by template):

// builder.Services.AddOpenTelemetryForAspNetCore(builder.Configuration, "EndPoint.WebAPI");

Keep it commented out if you don't have an OTLP backend.

---

Step 4: EF Core Features Configuration

What to change

Create EfCoreFeaturesConfig.cs (if you don't already have it) and register it from wherever you build your DB services.

Typical wiring points:

• If you use *.EndPoint.CommonConfigs/CommonHostConfig.cs, add:

  • services.AddFlexEfCoreFeatures(hostingContext.Configuration);

• Otherwise, add it in your DB configuration method (often DbEndPointConfig.AddFlexBaseDbServices(...)).

---

Step 5: Async Query Executor

What to change

Ensure your EF Core feature registration includes the async query executor, and update queries/handlers to use *AsyncFlex methods.

Examples:

var customers = await query.ToListAsyncFlex();
var customer = await query.FirstOrDefaultAsyncFlex();
var exists = await query.AnyAsyncFlex();

---

Step 6: Query Template Updates

What to change

In existing generated queries/handlers, update these patterns:

• .ToList() + Task.FromResult(...) → await ... .ToListAsyncFlex() and return directly

• .FirstOrDefault() + Task.FromResult(...) → await ... .FirstOrDefaultAsyncFlex() and return directly

---

Step 7: AppSettings Changes Summary

Add these sections if missing (merge into your environment-specific appsettings).

OpenTelemetry

"OpenTelemetry": {
  "Enabled": true,
  "ServiceVersion": "1.0.0",
  "OtlpExporter": {
    "Enabled": false,
    "Endpoint": "http://localhost:4317"
  }
}

FlexEfCore

"FlexEfCore": {
  "AuditTrail": {
    "Enabled": true,
    "IncludeAdded": true,
    "IncludeModified": true,
    "IncludeDeleted": true,
    "CaptureOldValues": true,
    "CaptureNewValues": true
  },
  "SoftDelete": {
    "Enabled": true
  }
}

RateLimiting (Optional)

"RateLimiting": {
  "Enabled": true,
  "FixedWindow": {
    "Enabled": true,
    "PermitLimit": 100,
    "WindowSeconds": 60,
    "QueueLimit": 0
  },
  "PerUser": {
    "Enabled": true,
    "PermitLimit": 50,
    "WindowSeconds": 60
  },
  "PerIp": {
    "Enabled": true,
    "PermitLimit": 30,
    "WindowSeconds": 60
  }
}

---

Step 8: Subscriber Idempotency (Optional)

Subscriber idempotency ensures each subscriber processes a given event only once (even if the bus retries delivery).

Configuration

"FlexIdempotency": {
  "Enabled": true,
  "StoreType": "Cache",
  "DefaultTimeToLiveDays": 7,
  "KeyPrefix": "flex:idempotency",
  "EnableAutoCleanup": false,
  "CleanupBatchSize": 1000
}

"FlexCache": {
  "MaxPayloadBytes": 1048576,
  "DefaultExpirationMinutes": 60
}

Startup wiring

Call this during service registration (where you register other Flex services):

services.AddFlexIdempotency(configuration);

If your solution does not have the EF Core idempotency package/namespace available yet, keep StoreType as Cache.

---

Step 9: AI-Assisted Upgrade Prompt

You are upgrading an existing FlexBase application to FlexBase 10.0.0-Dev-Build026.

Goal: Apply ONLY the changes described in this page, and ensure the solution builds.

Tasks:
1) Update appsettings files:
   - Add OpenTelemetry, FlexEfCore.
   - (Optional) Add RateLimiting.
   - (Optional) Add FlexIdempotency and FlexCache.

2) Apply code changes:
   - Exception handling: use FlexExceptionFilter and add app.UseFlexExceptionHandler() after CORS.
   - (Optional) Add rate limiting registration and middleware.
   - Ensure EF Core features are registered via AddFlexEfCoreFeatures(configuration).
   - Update generated queries/handlers to use *AsyncFlex methods.
   - (Optional) Add subscriber idempotency by wiring services.AddFlexIdempotency(configuration).

3) Validate:
   - Run dotnet build for the full solution.
   - If build fails, report the exact error and fix only what’s required for this upgrade.

Constraints:
- Do not add unrelated features.
- Keep changes minimal and consistent with existing solution structure.

---

FlexBase 9 to 10 Migration Steps

These steps help you align an existing FlexBase 9 solution with the FlexBase 10 solution structure.

The older folder structure is still supported, so you can upgrade and run without doing these immediately. That said, adopting the newer structure typically improves navigation, consistency across modules, and the overall visual organization of the solution.

Step 1: Folder Structure Alignment

FlexBase 10 introduces a cleaner application structure that groups related concerns together (contracts vs orchestration vs business logic). This is the first recommended step when moving from FlexBase 9 to 10.

Target Folder Layout (FlexBase 10)

Below is the recommended FlexBase 10 folder structure. Replace {YourApplication} with your application name.

{SolutionRoot}/
  DevNotes/                       (optional)

  {YourApplication}.Application/
    ControlContracts/
      {YourApplication}.DTOs/
        {YourApplication}.DTOs.csproj
      {YourApplication}.Messages/
        {YourApplication}.Messages.csproj
      {YourApplication}.SharedEvents/
        {YourApplication}.SharedEvents.csproj

    ControlHub/
      {YourApplication}.CronJobs/
        {YourApplication}.CronJobs.csproj
      {YourApplication}.WebControllers/
        {YourApplication}.WebControllers.csproj

    Domain/
      {YourApplication}.CommonLib/
        {YourApplication}.CommonLib.csproj
      {YourApplication}.DomainModels/
        {YourApplication}.DomainModels.csproj
      {YourApplication}.DomainModels.Tests/
        {YourApplication}.DomainModels.Tests.csproj
      {YourApplication}.Mappers/
        {YourApplication}.Mappers.csproj

    DomainHandler/
      {YourApplication}.Handlers/
        {YourApplication}.Handlers.csproj
      {YourApplication}.Handlers.Tests/
        {YourApplication}.Handlers.Tests.csproj
      {YourApplication}.PreBus/
        {YourApplication}.PreBus.csproj
      {YourApplication}.PreBus.Tests/
        {YourApplication}.PreBus.Tests.csproj
      {YourApplication}.Queries/
        {YourApplication}.Queries.csproj
      {YourApplication}.Queries.Tests/
        {YourApplication}.Queries.Tests.csproj
      {YourApplication}.RESTClients/
        {YourApplication}.RESTClients.csproj

    EndPoints/
      DbMigrations/
        {YourApplication}.Migrations.SqlServer/
          {YourApplication}.Migrations.SqlServer.csproj
        {YourApplication}.Migrations.PostgreSql/
          {YourApplication}.Migrations.PostgreSql.csproj
        {YourApplication}.Migrations.Tenant.SqlServer/
          {YourApplication}.Migrations.Tenant.SqlServer.csproj
        {YourApplication}.Migrations.Tenant.PostgreSql/
          {YourApplication}.Migrations.Tenant.PostgreSql.csproj

      {YourApplication}.EndPoint.CommonConfigs/
        {YourApplication}.EndPoint.CommonConfigs.csproj
      {YourApplication}.EndPoint.CronJob/
        {YourApplication}.EndPoint.CronJob.csproj
      {YourApplication}.EndPoint.Handlers.Default/
        {YourApplication}.EndPoint.Handlers.Default.csproj
      {YourApplication}.EndPoint.Subscribers.Default/
        {YourApplication}.EndPoint.Subscribers.Default.csproj
      {YourApplication}.EndPoint.WebAPI/
        {YourApplication}.EndPoint.WebAPI.csproj

    Infrastructure/
      Bus/
        {YourApplication}.Nsb/
          {YourApplication}.Nsb.csproj
      Db/
        {YourApplication}.BaseEF/
          {YourApplication}.BaseEF.csproj
        {YourApplication}.BaseEF.SqlServer/
          {YourApplication}.BaseEF.SqlServer.csproj
        {YourApplication}.BaseEF.PostgreSql/
          {YourApplication}.BaseEF.PostgreSql.csproj
      Providers/
        {YourApplication}.DataStoreProviders/
          {YourApplication}.DataStoreProviders.csproj

  {YourApplication}.Framework/
    Bridge/
      {YourApplication}.AspNetCoreBridge/
        {YourApplication}.AspNetCoreBridge.csproj
      {YourApplication}.CoreBridge/
        {YourApplication}.CoreBridge.csproj
      {YourApplication}.EFCoreBridge/
        {YourApplication}.EFCoreBridge.csproj

    PostBus/
      {YourApplication}.HandlerInterfaces/
        {YourApplication}.HandlerInterfaces.csproj
      {YourApplication}.Handlers.Default.Nsb/
        {YourApplication}.Handlers.Default.Nsb.csproj
      {YourApplication}.Subscribers.Default.Nsb/
        {YourApplication}.Subscribers.Default.Nsb.csproj

Note: Your solution may not include every database-specific project (e.g., only SqlServer migrations, no PostgreSql), and provider projects can vary by implementation. Keep the folder structure consistent and include only the projects that apply to your application.

Recommended Folder Moves / Renames

Use these mappings as guidance (project names are equivalent; focus on structure):

1. Queries

• Old: Application/Domain/{ProjectName}.Queries/

• New: Application/DomainHandler/{ProjectName}.Queries/

1. DTOs / Messages / Shared Events

• Old: Application/Dto/...

• New: Application/ControlContracts/...

1. Orchestration

• Old: Application/Orchestration/...

• New: Application/ControlHub/...

1. PreBus + REST Clients

• Old: Application/PreBus/... and Application/Orchestration/{ProjectName}.RESTClients/...

• New: Application/DomainHandler/{ProjectName}.PreBus/... and Application/DomainHandler/{ProjectName}.RESTClients/...

1. Handlers

• Old: Application/PostBus/{ProjectName}.Handlers.Plugins/...

• New: Application/DomainHandler/{ProjectName}.Handlers/

  • Suggested subfolders: CommandHandlers/ and Subscribers/

1. Infrastructure Providers

• Ensure Application/Infrastructure/Providers/ exists for provider-related code (and keep Bus/ and Db/ alongside it).

Naming Convention Update (NSB Handlers)

• Old pattern: *CommandHandler.cs

• New pattern: *NsbHandler.cs

This typically means renaming both the file and class suffix from CommandHandler → NsbHandler.