Release 2.6.0

Summary

NetCoreApplicationTemplate 2.6.0 completes the repository and distribution migration to the AsiBackbone organization while preserving the existing template and runtime compatibility surface.

Highlights

• Migrated repository and release metadata to AsiBackbone/NetCoreApplicationTemplate.
• Migrated the canonical repository-maintained container image to:
  ghcr.io/asibackbone/netcoreapplicationtemplate
• Updated Kubernetes examples and container documentation for the new GHCR namespace.
• Updated the GitHub Packages source to the AsiBackbone organization namespace.
• Updated generated scaffold references to the current repository and GitHub Pages documentation site.
• Updated release, citation, Zenodo, package, and documentation metadata for version 2.6.0.
• Added explicit public-surface guidance for repository ownership and registry namespace migrations.
• Updated GitHub CodeQL Action usage from 4.37.3 to 4.37.4.
• Updated Docker Login Action usage to 4.6.0.

Compatibility

This is a backward-compatible minor release.

The following remain unchanged:

• NuGet package ID: NetCoreApplicationTemplate
• Template short name: netcoreapp-template
• Template identity and group identity
• Supported template options
• Generated scaffold structure
• Application configuration surface
• Runtime application behavior

Previously published images under ghcr.io/cdcavell/netcoreapplicationtemplate remain available as historical release artifacts. New releases are published under the canonical ghcr.io/asibackbone/netcoreapplicationtemplate namespace.

Install

dotnet new install NetCoreApplicationTemplate::2.6.0

Release 2.5.0

Summary

NetCoreApplicationTemplate 2.5.0 is a backward-compatible minor release focused on production-oriented EF Core diagnostics, Kubernetes deployment hardening, and dependency/tooling maintenance.

This release introduces explicit configuration controls for optional EF Core diagnostics while keeping normal EF Core logging efficient by default. It also strengthens the Kubernetes deployment example and refreshes observability, SQLite runtime, and GitHub Actions dependencies.

Highlights

Configurable EF Core Diagnostics

NCAT now exposes optional EF Core diagnostics under:

{
  "ProjectTemplate": {
    "DataAccess": {
      "Diagnostics": {
        "EnableDetailedErrors": false,
        "EnableEfCoreTraceBridge": false
      }
    }
  }
}

Both settings default to false.

• EnableDetailedErrors enables EF Core EnableDetailedErrors() when deeper property-level diagnostic information is needed.
• EnableEfCoreTraceBridge enables EF Core's LogTo(...) stream and forwards it through ILogger<ApplicationDbContext> at Trace level.

Standard EF Core Microsoft.Extensions.Logging integration remains available without enabling either option.

Sensitive-data logging remains disabled. Enabling detailed errors or the trace bridge does not implicitly enable EnableSensitiveDataLogging().

The same diagnostic configuration is applied consistently to both scoped ApplicationDbContext instances and contexts created through IDbContextFactory<ApplicationDbContext>.

Save Pipeline Behavior Preserved

The existing ApplicationSaveChangesInterceptor remains active regardless of the optional diagnostic settings.

Disabling diagnostics therefore does not disable or alter the existing persistence pipeline, including auditing, canonicalization, mutation manifests, and related save lifecycle behavior.

Kubernetes Deployment Hardening

The Kubernetes deployment example has been strengthened with additional production-oriented defaults:

• RuntimeDefault seccomp profile
• Non-root execution using application-specific UID/GID 10001
• All Linux capabilities dropped
• Read-only root filesystem
• Explicit CPU and memory requests and limits
• Automatic Kubernetes service-account token mounting disabled
• Writable application data and logging volumes retained
• imagePullPolicy: Always
• Container image updated to the version-pinned 2.5.0 release

These changes reduce unnecessary container privileges while retaining the runtime capabilities required by the sample application.

Dependency and Tooling Updates

This release also refreshes several runtime and development dependencies, including:

• OpenTelemetry ASP.NET Core instrumentation 1.17.0
• OpenTelemetry HTTP instrumentation 1.17.0
• SQLitePCLRaw.bundle_e_sqlite3 3.0.4
• GitHub Actions checkout and .NET setup tooling
• GitHub CodeQL
• OpenSSF Scorecard
• Zizmor workflow security analysis
• Docker registry authentication tooling

NuGet dependency lock files have been refreshed to reflect the updated dependency graph.

Compatibility

Version 2.5.0 remains within the stable NCAT 2.x line.

There are no changes to:

• NuGet package ID: NetCoreApplicationTemplate
• Template short name: netcoreapp-template
• Internal template identity
• Template group identity
• Supported template options

Existing projects generated with earlier NCAT releases are not modified automatically.

Applications that do not configure the new EF Core diagnostics options retain the normal EF Core logging path without additional detailed-error or LogTo(...) diagnostic overhead.

Install

Install the template from NuGet:

dotnet new install NetCoreApplicationTemplate::2.5.0

Generate a new application:

dotnet new netcoreapp-template -n ContosoSecurityPortal

Resources

• NuGet: https://www.nuget.org/packages/NetCoreApplicationTemplate
• Documentation: https://cdcavell.github.io/NetCoreApplicationTemplate/
• Repository: https://github.com/cdcavell/NetCoreApplicationTemplate
• Production Deployment Checklist: https://cdcavell.github.io/NetCoreApplicationTemplate/articles/production-deployment-checklist.html
• EF Core Diagnostics: https://cdcavell.github.io/NetCoreApplicationTemplate/articles/ef-core-diagnostics.html
• Zenodo Concept DOI: https://doi.org/10.5281/zenodo.20373042

Release 2.4.0

Summary

Release 2.4.0 expands NCAT’s secure application baseline with authenticated-by-default routed endpoints, stronger authentication-cookie handling, forwarded-header trust diagnostics, and a substantial new audit-accountability and operational-integrity surface.

This is a backward-compatible minor release within the stable 2.x package line.

Highlights

Authenticated-by-default routed endpoints

The default scaffold now configures an ASP.NET Core fallback authorization policy requiring an authenticated user for routed endpoints that do not contain authorization metadata.

Public routes must be declared intentionally with [AllowAnonymous], .AllowAnonymous(), or equivalent anonymous metadata.

The --authProvider none template option remains available as an explicit architectural opt-out. It disables application authentication, cookie authentication, and the authenticated fallback authorization policy in generated configuration.

Stronger authentication-cookie security

Local authentication cookies now use CookieSecurePolicy.Always by default.

Applications that require plain HTTP during local development may enable:

{
  "ProjectTemplate": {
    "Authentication": {
      "Cookie": {
        "AllowInsecureHttp": true
      }
    }
  }
}

This override is accepted only in the Development environment and is rejected during startup in Testing, Staging, Production, and other environments.

Forwarded-header trust diagnostics

NCAT now detects deployments where forwarded client-IP processing and rate limiting are enabled without a deployment-specific trusted proxy or network.

Outside Development, the application logs a startup warning when this configuration could cause multiple clients to share a proxy rate-limit partition or cause client-IP logs to identify the proxy rather than the originating client.

Deployments may opt into fail-fast validation with:

{
  "ProjectTemplate": {
    "ForwardedHeaders": {
      "RequireExplicitProxyTrust": true
    }
  }
}

NCAT continues to rely on ASP.NET Core’s trusted-proxy protections and does not parse or trust arbitrary raw X-Forwarded-For values.

Audit accountability and integrity

Release 2.4.0 introduces a framework-neutral audit-accountability model for correlating application mutations with host-owned workflow, archive, SIEM, or governance records.

New capabilities include:

• Structured audit context for actor, request, operation, retry-attempt, decision, tenant, organization, correlation, trace, and span identifiers.
• One MutationBatchId shared by all audit records produced during a logical save.
• Minimized mutation audit receipts that exclude audited entity values.
• Host-replaceable audit value policies supporting include, mask, hash, omit, and truncate dispositions.
• Versioned canonical mutation manifests with deterministic ordering.
• SHA-256 manifest hashing and retained-batch verification contracts.
• DbContext-specific audit state and mutation-receipt isolation.

Canonical manifest verification proves correspondence between a receipt and a retained protected-value mutation batch. It does not by itself guarantee immutable storage, actor authenticity, legal compliance, transaction durability, or archive completeness.

Audited transaction coordination

Applications may opt into IApplicationAuditedTransaction to coordinate:

• Business mutations.
• NCAT audit rows.
• Database-generated value completion.
• Mutation receipt generation.
• Optional database-local completion handoffs.

Coordinator-owned operations use the configured EF Core execution strategy and a relational transaction. Existing transactions may be joined through savepoints while preserving responsibility for the outer commit or rollback.

Direct SaveChanges and SaveChangesAsync remain supported for applications that do not opt into transaction coordination.

Durable audit-completion outbox

NCAT now includes an optional, provider-neutral audit-completion outbox.

The outbox supports:

• Atomic staging with the originating application transaction.
• Stable destination and mutation idempotency keys.
• Post-commit dispatch.
• Bounded exponential retry behavior.
• Deferred delivery when no publisher is registered.
• Retryable, terminal failure, and dead-letter states.
• Minimized health and operator query projections.

The outbox is a durable local handoff. It is not a distributed queue and does not promise exactly-once delivery.

Audit reconciliation, health, and metrics

New reconciliation services compare retained mutation audit batches with completion-outbox records and detect:

• Missing completion records.
• Missing retained audit batches.
• Audit record count mismatches.
• Canonical manifest verification failures.
• Incomplete generated values.
• Malformed correlation.
• Duplicate completion records.
• Stale pending or retry-ready delivery.
• Terminal delivery failures.
• Dead-lettered work.

Reconciliation findings use stable reason codes, severities, remediation states, and append-only remediation evidence.

NCAT also exposes audit-integrity health status and provider-neutral metrics for open findings, manifest failures, missing completions, backlog size, pending age, retries, and dead letters.

Security and quality improvements

This release also includes:

• Property-based testing for persistence normalization and canonicalization invariants.
• NuGet dependency lock files and expanded locked-restore validation.
• Updated .NET, Entity Framework Core, OpenTelemetry, testing, and supporting dependencies.
• Stronger GitHub Actions token-permission scoping.
• Immutable action pinning and runner monitoring.
• Expanded OpenSSF Scorecard and Best Practices integration.
• Improved CodeQL, dependency-review, OWASP Dependency-Check, and release-evidence workflows.
• Expanded migration, template, Docker, authorization, authentication, and cross-platform smoke-test coverage.
• Removal of obsolete source and test placeholders.

Compatibility

• NuGet package ID remains NetCoreApplicationTemplate.
• Template short name remains netcoreapp-template.
• Internal template identity and group identity are unchanged.
• Existing generated projects are not modified automatically.
• Strict forwarded-header validation remains opt-in.
• Audited transaction coordination, completion outbox, reconciliation, and hosted workers remain opt-in.
• NCAT remains independent of AsiBackbone and does not require an external governance, archive, SIEM, or audit product.

Install

dotnet new install NetCoreApplicationTemplate::2.4.0

Generate the default authenticated scaffold:

dotnet new netcoreapp-template -n ContosoSecurityPortal

Generate the explicit authentication-disabled variant:

dotnet new netcoreapp-template `
  --name ContosoNoAuth `
  --authProvider none

Upgrade guidance

Installing version 2.4.0 updates the locally installed template for future project generation. Existing applications generated from earlier versions are not automatically changed.

Consumers adopting the new defaults manually should review:

• Fallback authorization configuration and explicitly anonymous routes.
• Authentication-cookie HTTPS requirements.
• Trusted proxy and forwarded-header configuration.
• EF Core migrations for the new audit-completion and reconciliation records.
• Audit value minimization policies before enabling production auditing.
• Retry, dead-letter, reconciliation, health, and alerting thresholds before enabling the outbox or scheduled reconciliation worker.

Release 2.3.1

Summary

Release 2.3.1 is a patch release focused on hardening centralized Problem Details exception classification.

This release changes the default handling of plain ArgumentException so broad internal/developer argument failures are treated as internal server faults instead of being classified as client bad-request traffic. Explicit request-level malformed input failures continue to use BadHttpRequestException and remain mapped to HTTP 400.

Changed

• Changed centralized Problem Details exception mapping so plain ArgumentException now maps to HTTP 500 Internal Server Error.
• Preserved BadHttpRequestException mapping to HTTP 400 Bad Request for request-level malformed input failures.
• Updated Problem Details tests to verify status code, title, and production detail-hiding behavior for both request-level and internal exception paths.
• Updated release metadata, package README examples, template packaging documentation, citation metadata, and Zenodo metadata for 2.3.1.

Compatibility

This is a patch release. It does not change the package identity, template identity, template short name, template options, or default scaffold purpose.

Existing consumers can update from 2.3.0 to 2.3.1 without changing template installation or scaffold commands.

Install

dotnet new install NetCoreApplicationTemplate::2.3.1

Update

dotnet new install NetCoreApplicationTemplate::2.3.1

Notes

This release strengthens diagnostics and production-safe error classification by ensuring internal argument failures contribute to server-error visibility instead of being silently treated as client-side bad requests.

Release 2.3.0

Summary

Release 2.3.0 hardens rate-limit client partition fallback behavior when HttpContext.Connection.RemoteIpAddress is unavailable.

Highlights

• Added explicit configuration for unknown-client rate-limit fallback behavior.
• Changed unresolved-client fallback behavior so requests no longer silently collapse into one shared "unknown-client" bucket by default.
• Added warning logging when rate limiting must use the fallback client partition path.
• Preserved the safer design of using ASP.NET Core Forwarded Headers Middleware as the trusted source for client IP resolution instead of parsing raw X-Forwarded-For values directly.
• Expanded documentation around trusted proxy configuration, KnownProxies, KnownNetworks, and middleware ordering.

New Configuration

Two rate-limiting settings were added:

"UseSharedUnknownClientPartition": false,
"UnknownClientPartitionKey": "unknown-client"

By default, unresolved clients now receive a per-request fallback partition. Set UseSharedUnknownClientPartition to true only when unresolved clients should intentionally share the configured unknown-client bucket.

Validation

This release also adds test coverage for:

• Resolved client IP partitioning.
• Default per-request fallback partitioning.
• Explicit shared fallback partitioning.
• Fallback warning logging.
• Rate-limiting option binding and validation.

Notes

This is a minor release because it adds new configuration surface and changes fallback behavior while preserving the stable 2.x package identity, template short name, template options, and default scaffold purpose.

Production deployments behind reverse proxies, load balancers, ingress controllers, CDNs, or gateways should verify forwarded-header trust configuration so rate limiting and request logging see the corrected client IP address.

Release 2.2.0

Summary

Release 2.2.0 is a minor release focused on improving the EF Core save pipeline architecture, reducing repeated ChangeTracker work, strengthening test coverage around the new interceptor path, and updating release metadata for the 2.2.x line.

Highlights

• Refactored EF Core save preparation into an application-owned IApplicationSaveChangesPipeline / ApplicationSaveChangesPipeline.
• Added ApplicationSaveChangesInterceptor as the composite EF Core save lifecycle interceptor.
• Moved save-pipeline invocation into EF Core SavingChanges / SavingChangesAsync and SavedChanges / SavedChangesAsync hooks.
• Reduced repeated ChangeTracker enumeration by materializing relevant entries once and reusing them across save-pipeline concerns.
• Reduced ApplicationDbContext save overrides to optimistic-concurrency exception handling around EF Core’s native save flow.
• Documented the EF Core save pipeline extension model, including when to replace or decorate IApplicationSaveChangesPipeline.
• Added ADR 0004 explaining the decision to keep the composite SaveChanges interceptor rather than splitting into specialized interceptors at this stage.
• Added branch-focused tests for ApplicationSaveChangesInterceptor, including constructor guard, non-ApplicationDbContext, and bounded after-save follow-up branches.
• Updated package, README, template packaging, citation, and Zenodo metadata for 2.2.0.

Compatibility Notes

This release preserves the stable 2.x package identity, template short name, template options, and default scaffold behavior.

The default generated scaffold continues to use:

• Package ID: NetCoreApplicationTemplate
• Template short name: netcoreapp-template
• Default authentication provider: cookie
• Default data provider: sqlite

No breaking changes are intended.

Upgrade

Install or update the template package with:

dotnet new install NetCoreApplicationTemplate::2.2.0

For a local packed package:

dotnet new install ./artifacts/template-package/NetCoreApplicationTemplate.2.2.0.nupkg

Validation

Before publishing, validate the release branch with the standard release gate, including:

./scripts/Validate-VersionConsistency.ps1

CI should confirm build, tests, coverage gate, template package creation, scaffold smoke tests, and documentation checks.

Release 2.1.0

Summary

Release 2.1.0 is a minor release focused on improving extensibility, release-surface clarity, and production guidance while preserving the stable 2.x package identity and default scaffold behavior.

Highlights

• Added a template-owned audit storage seam through IApplicationAuditStore.
• Added ProjectTemplate:DataAccess:Auditing:StorageMode with Local as the default storage mode.
• Added explicit audit extension modes: Outbox and ExternalSink.
• Preserved local EF Core audit storage as the default behavior.
• Added support for governance/audit package integration paths, including future AsiBackbone-style adapters.
• Short-circuited ApplicationDbContext.SaveChanges and SaveChangesAsync when the EF Core change tracker has no pending changes.
• Added optional application/domain layer guidance for consumers who outgrow the default Web / Infrastructure split.
• Expanded production authentication hardening guidance.
• Added middleware ordering rationale and documented order-sensitive pipeline invariants.
• Refreshed configuration, data-access, public-surface, README, package README, and template-packaging documentation.
• Reformatted documentation image assets for consistent repository and documentation display.

Audit Storage Extension Path

The default audit behavior remains unchanged. Audit records continue to use local EF Core storage unless a consuming application intentionally configures and registers a custom audit store.

Supported storage mode names:

• Local — built-in default local EF Core audit storage.
• Outbox — extension mode for durable handoff/outbox-style audit workflows.
• ExternalSink — extension mode for external governance, SIEM, audit, or companion package integrations.

Outbox and ExternalSink require a custom IApplicationAuditStore implementation.

Compatibility Notes

This release does not change the public package identity, template short name, template options, or default scaffold behavior.

Existing consumers do not need to change configuration unless they intentionally adopt a non-local audit storage mode.

Package

dotnet new install NetCoreApplicationTemplate::2.1.0

Validation

Release preparation updated version metadata, package release notes, changelog, README/package README examples, template-packaging documentation, citation metadata, and Zenodo metadata for 2.1.0.

Release 2.0.1

Summary

Release 2.0.1 is a patch release focused on post-2.0 documentation alignment, repository/package branding, release metadata, and Trusted Publishing readiness.

This release does not change the template short name, public package identity, template options, generated scaffold behavior, or the stable NetCoreApplicationTemplate NuGet package identity introduced in 2.0.0.

What Changed

Documentation and Release Metadata

• Refreshed post-2.0 documentation to align with the current NetCoreApplicationTemplate package identity.
• Updated README release references, install examples, package README examples, template-packaging documentation, citation metadata, and Zenodo metadata for 2.0.1.
• Updated release guidance, maintainer guidance, support policy, security policy, runtime readiness notes, telemetry notes, and Docker documentation to remove stale pre/post-1.0 language.

Repository Branding

• Replaced the repository/package icon assets with a new original NetCoreApplicationTemplate icon.
• Updated documentation-site branding so the new icon renders cleanly in the DocFX navigation experience.
• Documented the project-created branding assets in ASSETS-LICENSES.md.

Trusted Publishing Readiness

• Confirmed NuGet Trusted Publishing workflow permissions include the required GitHub Actions OIDC token permission for public package publication.

Package

Install the template from NuGet:

dotnet new install NetCoreApplicationTemplate::2.0.1

Update an existing installed template:

dotnet new install NetCoreApplicationTemplate::2.0.1

Create a new project:

dotnet new netcoreapp-template -n ContosoSecurityPortal

Compatibility Notes

• Package ID remains: NetCoreApplicationTemplate
• Template short name remains: netcoreapp-template
• Default authentication provider remains: cookie
• Default data provider remains: sqlite
• No generated scaffold behavior changes are included.
• No breaking changes are included.

Recommended Validation

Before publishing or after installing the package, validate with:

dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release
dotnet pack ./NetCoreApplicationTemplate.Template.csproj --configuration Release --output ./artifacts/template-package
dotnet new install ./artifacts/template-package/NetCoreApplicationTemplate.2.0.1.nupkg
dotnet new netcoreapp-template -n ContosoSecurityPortal

Full Changelog

See CHANGELOG.md for the complete release history.

Release 2.0.0

Summary

NetCoreApplicationTemplate 2.0.0 is a major release that simplifies the public NuGet package identity from CDCavell.NetCoreApplicationTemplate to NetCoreApplicationTemplate.

This release keeps the project’s core purpose intact: providing a production-oriented ASP.NET Core application template with structured logging, security headers, forwarded headers, rate limiting, centralized error handling, authentication-ready architecture, EF Core-ready structure, template validation, documentation, and CI release checks.

Breaking Change

The NuGet package ID has changed.

Old package ID:

CDCavell.NetCoreApplicationTemplate

New package ID:

NetCoreApplicationTemplate

Consumers should install the new package ID going forward.

Migration

If the previous package is installed locally, uninstall it first:

dotnet new uninstall CDCavell.NetCoreApplicationTemplate

Then install the new package:

dotnet new install NetCoreApplicationTemplate::2.0.0

Generate a new project:

dotnet new netcoreapp-template -n ContosoSecurityPortal

Changed

• Renamed the NuGet package from CDCavell.NetCoreApplicationTemplate to NetCoreApplicationTemplate.
• Updated package metadata for the simplified project-centered package identity.
• Updated README and package README installation examples for NetCoreApplicationTemplate::2.0.0.
• Updated release metadata and changelog documentation for the 2.0.0 release line.
• Switched NuGet.org publishing to NuGet Trusted Publishing.
• Updated GitHub Actions publishing flow to use OIDC-based trusted publication instead of a long-lived NuGet API key.

Notes

The previous CDCavell.NetCoreApplicationTemplate package should be treated as the legacy package identity and deprecated on NuGet with alternate package guidance pointing to NetCoreApplicationTemplate.

This package rename does not change the intended template functionality. The template remains focused on a practical ASP.NET Core baseline with secure defaults, structured application infrastructure, CI validation, and package-based dotnet new scaffold support.

Release 1.0.4

Summary

Release 1.0.4 is a patch-level maintenance release for NetCoreApplicationTemplate.

This release updates the SQLite dependency path by adding SQLitePCLRaw.bundle_e_sqlite3, replacing deprecated SQLite bundle usage with the supported bundled native SQLite provider.

Changes

• Added SQLitePCLRaw.bundle_e_sqlite3 package reference.
• Added the centrally managed package version for SQLitePCLRaw.bundle_e_sqlite3.
• Updated release/version metadata from 1.0.3 to 1.0.4.
• Updated CHANGELOG.md, README.md, PACKAGE-README.md, CITATION.cff, and .zenodo.json for the 1.0.4 release.

Notes

• This is a dependency maintenance release.
• No application behavior, public APIs, or template structure were intentionally changed.
• Existing consumers do not need to change their usage of the template.