Csag.Blueprint.Application
0.11.0
dotnet add package Csag.Blueprint.Application --version 0.11.0
NuGet\Install-Package Csag.Blueprint.Application -Version 0.11.0
<PackageReference Include="Csag.Blueprint.Application" Version="0.11.0" />
<PackageVersion Include="Csag.Blueprint.Application" Version="0.11.0" />
<PackageReference Include="Csag.Blueprint.Application" />
paket add Csag.Blueprint.Application --version 0.11.0
#r "nuget: Csag.Blueprint.Application, 0.11.0"
#:package Csag.Blueprint.Application@0.11.0
#addin nuget:?package=Csag.Blueprint.Application&version=0.11.0
#tool nuget:?package=Csag.Blueprint.Application&version=0.11.0
Csag.Blueprint.Application
Overview
This package provides application-layer abstractions for CSAG Blueprint-based applications: service interfaces, claim type constants, tenant context management, and a full table view query system. It sits between Domain and Infrastructure, defining contracts that infrastructure and app layers implement.
JSON
BlueprintJsonOptions holds the shared System.Text.Json conventions: camelCase names, string enums, LocalDateTimeJsonConverter and InstantJsonConverter.
LocalDateTimeJsonConverter writes a DateTime as a local reading yyyy-MM-ddTHH:mm:ss (no fraction, no offset) and reads yyyy-MM-ddTHH:mm[:ss]. A value with a UTC offset or Z is refused with a JsonException, which the API answers with 400. Writing a DateTime whose Kind is Utc or Local throws an InvalidOperationException: such a value holds an instant or the server's clock, not a reading. EF Core reads datetime2 columns as Unspecified, and TimeZones and the time values return readings with that kind. LocalDateTimeFormat holds the reading's text form (Format, TryParse, GetInvalidMessage), so query binding and table view filters accept exactly the same values, and Format refuses those kinds for every writer, OpenAPI examples included.
InstantJsonConverter reads a DateTimeOffset with System.Text.Json's own ISO 8601 parser, but only when it carries a UTC offset or Z: a value without one, which that parser reads in the server's zone, and a date on its own are refused with a JsonException (400). Writing is System.Text.Json's. It applies to DateTimeOffset? and to dictionary keys too. InstantFormat.TryParse holds the rule, so query binding accepts exactly the same instants.
Claims
IdentityClaimTypes: Static constants for identity claim types used across the application (TenantId,Permission,PreferredLanguage). They are stored in the authentication ticket so they are available on every request without a database lookup.ServiceAccountClaimTypes: The claim names a service-account bearer token and its principal carry —Subject(sub, the client id),Name(name),Type(type, alwaysServiceAccountType) andSessionId(sid, the opaque session reference). The bearer scheme does not map inbound claims, so these raw names are what the principal carries.
Tenant Context
TenantContext: AmbientAsyncLocal-backed storage for the current tenant ID. Set by middleware, read by query filters, save interceptors, and application code viaSetTenant(),Current, andClear().
Service Abstractions
All service contracts are defined as interfaces for dependency injection and testability.
| Interface | Purpose |
|---|---|
ITenantService |
Reads the current tenant ID from the authenticated user's claims. |
ITenantTimeZoneProvider |
Implemented by the application to supply the current tenant's IANA zone, which decides "today" and calendar days for the tenant. Returns TimeZoneInfo.Utc when there is no tenant or it has no zone. The packages register a UTC fallback with TryAdd, so register yours before or after the Blueprint registrations. |
ISessionLifecycle |
The application's entry point into the cookie session lifecycle. Seven intents — credentials changed, access revoked, claims changed, tenant removed, switch my session's tenant, list my sessions, revoke one of my sessions — decide which sessions end and which keep running with rebuilt claims. RevokeMySessionAsync returns false when the caller's account has no session with that id. No intent takes a CancellationToken: call it after the commit, and retry it on failure. |
ISessionRevocationParticipant |
Implemented by the application to end its own credentials (refresh tokens, API keys) whenever a revoking intent ends sessions. Every participant runs; failures are reported together. Each SessionRevocation names its SessionSubject — a user or a service account. |
ISessionEligibility |
Implemented by the application to answer "may this account hold a session?", asked at every sign-in and sliding renewal. Without one, every account may. |
ITenantMembershipChecker |
Answers whether a user is a member of a tenant without the tenant type parameters; the tenant manager implements it. |
IServiceAccountCredentials |
The application's entry point into service-account credentials: IssueTokenAsync (client id and secret to a ServiceAccountTokenResult — Issued, InvalidCredentials or AccountInactive), CreateCredentialsAsync and RotateSecretAsync (each returns the secret once as ServiceAccountClientCredentials). No CancellationToken. |
IServiceAccountSessionLifecycle |
The service-account counterpart of ISessionLifecycle: AccountDeactivatedAsync and AccountDeletedAsync end the account's sessions and tell the revocation participants, with a service-account SessionSubject. |
IServiceAccountClaimsEnricher |
Implemented by the application to add its own claims to a service-account principal on every request it authenticates. |
IPasswordResetEmailService |
Sends password reset emails containing a reset link. |
IImageStorageService |
Stores and deletes images with support for multiple backends (database or blob storage). Returns a StoredImageData record with binary data or URL depending on the implementation. |
Table View System
A generic, permission-aware system for server-side filtered, sorted, and paginated data grids. Application code defines views using a fluent API; infrastructure executes them against EF Core.
Defining a table view
Subclass TableViewDefinition<TEntity, TDto> and configure columns in the constructor:
public sealed class UserTableViewDefinition : TableViewDefinition<UserEntity, UserDto>
{
public UserTableViewDefinition()
{
Column(dto => dto.Name)
.Filterable(TableViewFilterOperator.Contains)
.Sortable();
Column(dto => dto.Email)
.Filterable(TableViewFilterOperator.Contains)
.Sortable();
ComputedColumn("FullName", entity => entity.FirstName + " " + entity.LastName, dto => dto.FullName)
.Sortable();
}
}
Key components
| Component | Purpose |
|---|---|
TableViewDefinition<TEntity, TDto> |
Abstract base class with a fluent API for configuring columns, filters, sorting, and projection. |
TableViewColumnDefinition<TEntity, TDto> |
Fluent builder for a single column. Call Filterable(), Sortable(), and WithDescription() to configure. |
ITableViewDefinitionInfo |
Static metadata interface (ViewId, DisplayName, RequiredPermission) so infrastructure can discover endpoints without entity-specific code. |
ITableViewCatalogRegistration |
Registration contract for views in the catalog. Implementations are automatically discovered via DI. |
ITableViewCatalogService |
Discovers available table views filtered by user permissions. |
ITableViewExecutor |
Executes a TableViewQueryRequest: applies filters, counts, sorts, paginates, and projects to DTOs. |
ITableViewPreferencesService |
Persists per-user view preferences (column visibility, order, width, pinning, filters, sort, page size). |
Column data types
TableViewColumnMetadata.DataType is derived from the DTO property type; TableViewDataTypes holds the values. Temporal columns report what kind of value they hold, so clients format them differently:
| CLR type | dataType |
Wire value | Shown as |
|---|---|---|---|
DateOnly |
date |
2026-10-21 |
the date |
DateTime |
localDateTime |
2026-10-26T10:00:00, no offset |
the reading, as it reads |
DateTimeOffset |
instant |
2026-10-26T09:00:00+00:00 |
in the viewer's zone |
A DateTime in a table view DTO is always a local reading; use DateTimeOffset for instants.
A local reading is in the tenant's zone unless the column says its zone comes from the row. A place elsewhere — a site the tenant runs, or a one-off venue such as a boat-show stand in Miami for a Zurich tenant — stores its own IANA zone id, and a table can then list readings in several zones:
Column(dto => dto.OpensLocal)
.Filterable(TableViewFilterOperator.DateRange)
.WithTimeZoneFrom(dto => dto.TimeZoneId); // the stand's own zone, per row
Column(dto => dto.TimeZoneId); // must be a column, so every row carries it
The column's metadata names the zone column in TimeZoneColumn ("TimeZoneId"), so a client labels each reading with its row's zone. Filters are unaffected: local readings compare as they read. WithTimeZoneFrom is refused on a column that is not a local reading and for a selector that does not name a property of the DTO itself (dto => dto.Venue.TimeZoneId), and the definition's Metadata throws when the zone property is not a column.
An entity's time values (PlaceTime, ZonedTime in Csag.Blueprint.Domain.Time) are not columns themselves. Give the DTO a flat property per member it shows and select the member; each column then has the data type of its kind and filters, sorts and exports in SQL like a column over a plain property. The members a DTO picks decide how a ZonedTime shows: a stand's opening as its reading in its own zone, an online briefing as an instant in each viewer's zone:
Column(dto => dto.StartLocal, e => e.Start.Local); // localDateTime, in the tenant's zone
Column(dto => dto.StartAt, e => e.Start.At); // instant
Column(dto => dto.StandOpensLocal, e => e.StandOpens.Local) // localDateTime, in the stand's zone
.WithTimeZoneFrom(dto => dto.StandOpensTimeZoneId);
Column(dto => dto.StandOpensTimeZoneId, e => e.StandOpens.TimeZoneId);
Column(dto => dto.BriefingAt, e => e.Briefing.At); // instant, in the viewer's zone
Filter operators
| Operator | Description |
|---|---|
Equals |
Exact match (column = value) |
Contains |
Substring match (column LIKE %value%) |
Range |
Numeric range (column BETWEEN min AND max) |
In |
List match (column IN (...)) |
Boolean |
True/false filter |
DateRange |
Calendar-date range (see below) |
Enum |
Enum value filter with predefined allowed values |
Date ranges and time zones
A DateRange filter value is from,to in yyyy-MM-dd, either side optional. Its meaning follows the column's kind:
date:from <= value <= to.localDateTime:value >= from 00:00andvalue < (to + 1 day) 00:00, on the reading as stored; no zone is involved.instant:value >= start of fromandvalue < start of (to + 1 day), with the days as they begin in the effective zone (TimeZones.DayRange), so a day can span 23 or 25 hours.
A range never matches a row without a value, not even ,9999-12-31, which has no bound because the day after it cannot be represented.
The effective zone is TableViewQueryRequest.TimeZone; when it is null, the executor asks ITenantTimeZoneProvider, which answers UTC unless the application registers its own. TableViewDataRequest and TableViewExportRequest carry it as an optional timeZone field (an IANA id, normally the viewer's browser zone); a value without the IANA form is a 400 validation error, while a well-formed id this host's time zone data does not know (browsers can be ahead of the server) falls back to the tenant zone with a warning logged. An Equals or In filter on an instant column reads a value without an offset in the same zone; a reading that does not exist there (a spring-forward gap) matches no row.
ITableViewDefinition.GetFilterExpression takes the zone. TableViewDefinition keeps a two-argument overload, for tests and other zone-free callers, that evaluates instant filters in UTC.
Allowed values and labels
Enum and In filters offer a column's AllowedValues, each a TableViewAllowedValue serialized as { "value": "...", "label": "..." }. Filters match on value; label is display text.
An enum column derives one entry per member: the member name as the value, the humanized name as the label (CreditCard → "Credit card", SMSCode → "SMS code"), and Enums.{EnumTypeName}.{MemberName} as the label's translation key. The key is optional: add it to the translation catalog to translate the label, otherwise the humanized label is served.
Column(dto => dto.PaymentMethod)
.Filterable(TableViewFilterOperator.Enum)
.WithValueLabelKeyPrefix("Payments.Methods"); // keys "Payments.Methods.{Value}", warned when missing
Column(dto => dto.Size)
.Filterable(TableViewFilterOperator.In)
.WithAllowedValues([new("S", "Small"), new("L", "Large") { LabelKey = "Sizes.Large" }]);
WithAllowedValues(IEnumerable<string>) and Filterable(operator, allowedValues) take plain strings, served with the string itself as the label. Excel exports write matching cells as their label.
Request / Result models
TableViewDataRequest: Incoming request with filters, sort, page, page size, and an optionaltimeZone.TableViewExportRequest: Incoming export request with filters, sort, an optional page, and an optionaltimeZone, which also decides the zone the workbook shows instants in.TableViewQueryRequest<TEntity, TDto>: Internal request that pairs a baseIQueryablewith aITableViewDefinition, pagination parameters, and the zone filters are evaluated in.TableViewDataResult<TDto>: Response with column metadata, data, total count, and computed page info.TableViewPreferencesModel: Serializable user preferences for a specific view.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Csag.Blueprint.Domain (>= 0.11.0)
- Microsoft.AspNetCore.Identity.EntityFrameworkCore (>= 10.0.13)
- Microsoft.EntityFrameworkCore (>= 10.0.13)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Csag.Blueprint.Application:
| Package | Downloads |
|---|---|
|
Csag.Blueprint.Infrastructure
Database, session, tenancy, localization, and authorization infrastructure for CSAG Blueprint applications. |
|
|
Csag.Blueprint.Realtime.AzureSignalR
Azure SignalR Service provider for the CSAG Blueprint real-time channel: tenant-scoped publishing over the serverless REST API and client connection tickets. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.11.0 | 105 | 11/13/2026 |
| 0.10.0 | 209 | 11/11/2026 |
| 0.9.0 | 206 | 11/10/2026 |
| 0.8.0 | 380 | 10/30/2026 |
| 0.7.0 | 202 | 10/28/2026 |
| 0.6.0 | 318 | 10/23/2026 |
| 0.5.0 | 540 | 10/20/2026 |
| 0.4.0 | 1,036 | 10/14/2026 |
| 0.3.0 | 1,135 | 9/15/2026 |
| 0.2.0 | 393 | 9/8/2026 |
| 0.1.3 | 819 | 8/20/2026 |
| 0.1.2 | 238 | 8/19/2026 |
| 0.1.1 | 197 | 8/13/2026 |
| 0.1.0 | 177 | 7/3/2026 |