PolyhydraGames.Core.AspNet 2.0.0.17

Core.AspNet

Shared ASP.NET Core helpers used across PolyhydraGames services and clients. The package focuses on common identity, logging, and controller building blocks so you can keep app code small and consistent.

Tags

• dotnet
• core
• core-asp-net
• docs
• testing
• devops

Related Repos

• Core
• Core.Models
• Core.Interfaces
• Core.Extensions
• Core.Serialization
• Core.SQL

Features

• Base API controllers for DTO and named DTO read endpoints
• Identity services for API, Blazor Server, and client-side apps
• OpenId Connect refresh token support
• Owner ID middleware for propagating authenticated user ID
• Jwt and HttpContext helpers
• Logging registration with Seq support

Requirements

• .NET SDK 10.0 (targets net10.0)
• ASP.NET Core authentication packages (transitive via NuGet)

Installation

dotnet add package PolyhydraGames.Core.AspNet

Quick Start

Register logging

var builder = WebApplication.CreateBuilder(args);
builder.AddLogs();

Add owner middleware

var app = builder.Build();
app.UseAuthentication();
app.UseOwnerMiddleware();

Add refresh middleware

var app = builder.Build();
app.UseAuthentication();
app.UseRefreshMiddleware();

Use base controllers

public class WidgetsController : DtoBaseController<WidgetDto>
{
    public WidgetsController(IReadByIdServiceAsync<WidgetDto> repo) : base(repo) { }
}

Configure identity services

// API
services.AddScoped<IIdentityService, ApiIdentityService>();

// Blazor Server
services.AddScoped<IIdentityService, ServerSideIdentityService>();

// Client-side (OidcClient provided by your app)
services.AddScoped<IAuthenticationClient, ClientSideIdentityService>();

Configuration

Refresh middleware

Refresh middleware expects standard OIDC configuration keys:

OIDC:Authority
OIDC:ClientId
OIDC:ClientSecret

The middleware uses OIDC discovery to resolve the token endpoint and stores refreshed tokens in authentication properties so GetTokenAsync continues to work.

Token expiration

Token expiry checks use the standard JWT exp claim via JwtSecurityToken.ValidTo. If the access token is missing or empty, it is treated as expired.

API Notes

Controllers

• DtoBaseController<T> exposes Items, Page, Count, Any, and ItemById.
• NamedDtoBaseController<T> adds name-based queries like ItemsByName and ItemByName.
• Use IReadByIdServiceAsync<T> for DTO controllers and INamedReadServiceAsync<T> for named DTO controllers to enforce compile-time contracts.

Identity services

• ApiIdentityService is for API hosts where owner ID is provided in tokens.
• ServerSideIdentityService listens to AuthenticationStateProvider in Blazor Server.
• ClientSideIdentityService wraps OidcClient for interactive login flows.
• AuthenticationStateExtensions.ToPrincipalContext() and AuthenticationStateProvider.GetCurrentPrincipalContextAsync() provide a reusable authenticated-principal snapshot containing the source principal, authentication status, owner ID, and best-effort display username. Use these helpers when app-level authorization needs principal claims before local app-user records have hydrated.

Middleware

• OwnerMiddleware sets IIdentityService.OwnerId and AuthorizationToken.
• RefreshMiddleware attempts a refresh token flow when JWTs are expired.

Build and Test

dotnet build
dotnet test

Sample Host (Middleware Testing)

A minimal sample app is available at samples/CoreAspNet.SampleHost/ to exercise UseOwnerMiddleware() and UseRefreshMiddleware().

Quick test flow

# from repo root
cd /home/lancer1977/code/Core.AspNet

# run the sample host
dotnet run --project samples/CoreAspNet.SampleHost

In another terminal:

curl http://localhost:5000/debug/identity

Expected result: JSON containing OwnerId, HasAccessToken, and token metadata populated by the sample auth handler + middleware.

appsettings.Development.json in the sample includes placeholder OIDC:* keys:

• OIDC:Authority
• OIDC:ClientId
• OIDC:ClientSecret

Contributing

• Keep public APIs documented with XML comments.
• Add tests for new middleware or identity behaviors.
• Follow existing naming and namespace conventions.

CI/CD Configuration

GitHub Actions handles build, test, pack, and publish.

Workflows

• ci.yml builds and tests on pushes and pull requests.
• publish.yml validates, packs, and publishes to NuGet.org only for version tags (v<PackageVersion>) or an explicit manual dispatch. It never publishes on a branch push.

Package Publishing

NuGet.org is the canonical package host. The currently published source version is 1.1.0.1; update <Version> in src/PolyhydraGames.Core.AspNet.csproj before creating a future v<PackageVersion> release tag. The package workflow verifies the package identity, version, and README inclusion before release.

📖 Documentation

Detailed documentation can be found in the following sections:

• Feature Index
• Core Capabilities
• Roadmap Index
• GitHub Actions