IronAlpine.Framework.Abstractions 2.0.0

IronAlpine.Framework.Abstractions

Why

Shared framework contracts used across logging, messaging, web metadata, and observability integrations.

Key Contracts

• IEventMetadataProvider
• IEventMetadataAccessor
• EventMetadataContext
• ICurrentUser
• IAuditUser
• IExecutionModeDetector

Installation

dotnet add package IronAlpine.Framework.Abstractions

Execution Modes

Execution mode detection enables framework packages to adjust runtime behavior safely in EF design-time operations.

Event Metadata

EventMetadataContext carries:

• TraceId
• CorrelationId
• CausationId
• TenantId
• transport metadata map

IEventMetadataProvider is the read-only surface used by other packages.

IEventMetadataAccessor is the read/write ambient context contract used by runtime entry points such as HTTP middleware or messaging processors.

Combinations

• Web.AspNetCore: fills metadata context from HTTP headers/activity.
• Messaging.*: consumes metadata for envelope/header enrichment and can establish metadata scope while processing a consumed message.
• Logging.Serilog: enriches logs with correlation fields.
• Observability.OpenTelemetry: tags spans with metadata.

Troubleshooting

• If correlation fields are empty, verify middleware order and metadata provider registration.
• If HTTP-originated events have correlation but event-to-event chains lose causation, verify the messaging runtime is setting IEventMetadataAccessor during inbox processing.

Configuration Deep Dive

When a package exposes options classes, use builder.Configuration binding and keep values explicit per environment.

Common guidance:

• Prefer explicit values in production.
• Keep retries/timeouts conservative; tune with telemetry.
• Enable startup validation in non-development environments.
• Fail fast when required dependencies are missing.

Integration Patterns

Pattern A: API service with EF + Messaging

1. Register EF provider package.
2. Register messaging inbox/outbox package.
3. Register mediator and behavior order.
4. Enable health readiness checks for DB and broker.

Pattern B: Read-heavy service with Dapper + Messaging

1. Register Dapper data package.
2. Register messaging package with consumer enabled.
3. Add observability and structured logging.

Pattern C: Security-focused service

1. Register security ASP.NET package.
2. Add policy catalog or resolver.
3. Register authorization EFCore projection package only where needed.

Options Checklist

Use this checklist when configuring any IronAlpine package:

• Required connection strings present.
• Feature flags intentional (Enable* values reviewed).
• Retry and timeout values match SLO expectations.
• Startup validation behavior understood.
• Environment-specific defaults are overridden in production.

Troubleshooting Matrix

• Startup failure with validation error : A required dependency package or config value is missing. Check package registrations and bound options sections.
• Background workers not starting : Verify execution mode, Enable* flags, and hosted services registration.
• Policy/authorization mismatch : Check claim types, policy naming strategy, and catalog entries.
• Cache stale or no-hit behavior : Validate key generation, invalidation path, and distributed lock configuration.
• Messaging duplicate handling issues : Verify event-id propagation and idempotency key construction.

Best-Practice Notes

• Keep handler logic deterministic and side-effect boundaries explicit.
• Keep IQueryable usage inside application handlers/services.
• Keep transaction save boundaries in handlers where business intent is clear.
• Prefer explicit topic policy metadata for critical events.