TaskHub.Shared

TaskHub.Shared.Bootstrapping - Technical Manual

The TaskHub.Shared.Bootstrapping modules provide the standardized application host templates that enforce the TaskHub Architectural Standard across all microservices. They eliminate “Startup Glue” code by providing pre-configured builders that wire up observability, security, persistence, and messaging in a consistent, predictable way.

🏛 Deep Architecture

1. BasicHostBuilder (The Foundation)

The BasicHostBuilder is the root of the hierarchy. It configures the minimal “must-have” infrastructure for any TaskHub service:

• JSON Strategy: Configures System.Text.Json with JsonStringEnumConverter and PropertyNamingPolicy.CamelCase. It ensures that all TaskHub APIs speak the same JSON dialect.
• Global Exception Filter: Injects a specialized filter that catches DomainException, ResultException, and generic Exception types. It automatically converts them into a Result or ValueResult<T> with standard status codes (400, 403, 404, 500), ensuring the client never receives a raw stack trace.
• Minimal DI: Registers IHttpContextAccessor and basic configuration tools.

2. FullHostBuilder (The “Batteries-Included” Template)

Inheriting from BasicHostBuilder, the FullHostBuilder orchestrates the entire solution’s project graph:

1. Observability Setup: Calls AddAppSerilog, AddAppOpenTelemetry, and AddAppMetrics.
2. Infrastructure Setup: Wires up Redis (AddAppRedis) and Networking (AddAppNetworkingSettings).
3. Persistence Lifecycle:
   • Registers the service-specific DbContext and UnitOfWork.
   • Startup Migrations: Automatically scans the database and applies pending EF Core migrations. This ensures that every deployment (CI/CD) is self-consistent with its database schema.
4. Security Integration: Configures JWT Bearer authentication and the UserStatusMiddleware.
5. CQRS Pipeline: Registers the CommandsBus and scans assemblies for Handlers and Behaviors.
6. Documentation: Configures Swagger with support for JWT authorization and API versioning.

---

🛠 API Reference

BasicHostBuilder(string[] args)

| Method | Description | | :— | :— | | void Start() | Initializes the WebApplicationBuilder with basic settings. | | Task Run() | Builds and starts the WebApplication. |

FullHostBuilder(string[] args)

| Method | Description | | :— | :— | | void Start<TContext>(Action<WebApplicationBuilder>? config = null) | Full infrastructure initialization including database context TContext. | | Task Run<TContext>() | Performs migrations and starts the host. |

---

🚀 Startup Flow & Sequence

When FullHostBuilder.Run<TContext>() is called, the following execution sequence occurs:

1. Configuration Loading: Merges appsettings.json, appsettings.{Env}.json, and Environment Variables.
2. DI Registration:
   • ServiceInfo (Refactoring)
   • Serilog (Logging)
   • OpenTelemetry (Tracing/Metrics)
   • Redis (Caching)
   • CommandsBus (CQRS)
   • AppAuthorization (Security)
   • AppNetworking (Resilience)
3. Context Migration: A temporary DI scope is created, TContext is resolved, and db.Database.MigrateAsync() is executed.
4. Middleware Pipeline:
   • ForwardedHeaders
   • SerilogRequestLogging
   • ExceptionHandler (Custom)
   • HttpsRedirection
   • Routing
   • Authentication & Authorization
   • UserStatusMiddleware (TaskHub Security)
   • Endpoints (Controllers, Metrics, etc.)

---

⚙️ Configuration Requirements

A service using FullHostBuilder requires the following sections in appsettings.json:

• Service: Name and version.
• Persistence: Connection string and feature flags.
• Jwt: Key and Issuer.
• Networking: Defaults and node URLs.
• Metrics: Port and labels.
• OpenTelemetry: OTLP endpoint.

---

✅ Best Practices & Anti-Patterns

🟢 Best Practices

• Use FullHostBuilder for APIs: It ensures you don’t forget critical things like correlation IDs, request logging, or database migrations.
• Custom Config in Action: Use the Action<WebApplicationBuilder> argument in Start() for service-specific registrations to keep Program.cs clean.

🔴 Anti-Patterns

• Manual Migrations: Avoid running dotnet ef database update manually in production; let the FullHostBuilder handle it to ensure atomicity between code and schema.
• Overriding Pipeline Order: Do not manually change the middleware order in FullHostBuilder unless you have a deep understanding of how it affects the UserStatusMiddleware and Result filters.

This site is open source. Improve this page.