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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Csag.Blueprint.Application" Version="0.11.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Csag.Blueprint.Application" Version="0.11.0" />
                    
Directory.Packages.props
<PackageReference Include="Csag.Blueprint.Application" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Csag.Blueprint.Application --version 0.11.0
                    
#r "nuget: Csag.Blueprint.Application, 0.11.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Csag.Blueprint.Application@0.11.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Csag.Blueprint.Application&version=0.11.0
                    
Install as a Cake Addin
#tool nuget:?package=Csag.Blueprint.Application&version=0.11.0
                    
Install as a Cake Tool

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, always ServiceAccountType) and SessionId (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: Ambient AsyncLocal-backed storage for the current tenant ID. Set by middleware, read by query filters, save interceptors, and application code via SetTenant(), Current, and Clear().

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:00 and value < (to + 1 day) 00:00, on the reading as stored; no zone is involved.
  • instant: value >= start of from and value < 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 optional timeZone.
  • TableViewExportRequest: Incoming export request with filters, sort, an optional page, and an optional timeZone, which also decides the zone the workbook shows instants in.
  • TableViewQueryRequest<TEntity, TDto>: Internal request that pairs a base IQueryable with a ITableViewDefinition, 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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