GerstITS Framework Examples

This solution demonstrates all features of the GerstITS framework packages in a small, coherent customer management domain.

Solution layout

Project	Purpose
GerstITS.Examples.Api	ASP.NET Core Web API host: fluent controllers, minimal API endpoints, versioning, exception handling, Swagger, authentication, session cache, jobs and auto migration.
GerstITS.Examples.Logic	Business logic: providers, search engine integration, validation rules, customizations and AutoMapper profiles.
GerstITS.Examples.Data	Data access: entities with framework aspects, EF Core DbContext, entity mappings, database configurator and migrations.
GerstITS.Examples.Jobs.SayHelloWorld	Scheduled Quartz jobs with cron configuration.
GerstITS.WebClients.Example.Api	Typed REST client contract for the example API (ICustomer).
GerstITS.Examples.WebClient.Console	Console client consuming the API via IWebClient plus demos of the common/system utilities.
GerstITS.Examples.Tests	xUnit tests using the GerstITS test framework categories.

Feature matrix

GerstITS.Common

Feature	Example
String/object/enum/enumerable extensions	WebClient.Console/Tests/CommonFeaturesRunner.cs
Fluent exception handling (Is(...).ThenThrows<...>().WithMessage(...))	CommonFeaturesRunner.cs, Logic/Customers/CustomerProvider.cs (Import)
Range<T> + Intersects	CommonFeaturesRunner.cs
AES cryptography extensions (Encrypt/Decrypt)	CommonFeaturesRunner.cs
ApplicationEnvironment detection	Api/Program.cs (IsEfCoreActionStarted)

GerstITS.System

Feature	Example
ISystemClock	MaintenanceController.Ping, SayHelloWorldJob
IJsonConvert	Api/Common/StartupTasks/ExampleStartupTask.cs, CommonFeaturesRunner.cs
IActivator	CommonFeaturesRunner.cs
ICache (encrypted, session backed)	Api/Controllers/1.1/CacheController.cs
Customizations (CustomizationBase<T>, ApplyCustomizations())	Logic/Customers/Customizations/CustomerDisplayNameCustomization.cs
Configuration prefix pattern (ToConfigurationPrefix)	Api/Common/Configurations/WebApiConfiguration.*.cs

GerstITS.IoC / GerstITS.IoC.DotNetCore

Feature	Example
IIoCModule<IServiceCollection> modules (partial pattern)	Module.cs in every project
DotNetCoreApplicationBootstrapper + IApplicationStart	WebClient.Console/Program.cs, Tests/TestRunner.cs, Tests/CommonFeaturesRunner.cs
IStartupTask with priorities	Api/Common/StartupTasks/ExampleStartupTask.cs
Namespace based assembly scanning (Register...Of<T>())	Logic/Module.Customers.cs

GerstITS.Data / GerstITS.Data.EntityFramework / GerstITS.Data.EntityFramework.PostgreSql

Feature	Example
EntityBase<TKey> + aspects (IActivatable, ICreatable, IModifiable, IVersionable)	Data/Entities/CustomerEntity.cs
Historization (IHistoricizable)	Data/Entities/CustomerNoteEntity.cs
EntityMappingBase<TEntity>	Data/Mappings/*.cs
EntityFrameworkDbContextBase + IDbContext	Data/CustomerDbContext.cs
PostgreSqlDatabaseConfiguratorBase<TDbContext>	Data/Migrations/CustomerDatabaseConfigurator.cs
Design time factory + migrations	Data/Migrations/DesignTime/CustomerDbContextDesignTimeFactory.cs, Data/Migrations/20260703*_InitialCreate.cs
Registration (AddMigration, AddEntityFrameworkSession)	Data/Module.cs
Repository queries (active only by default, includeInactive opt-in)	Logic/Customers/CustomerProvider.cs (GetById)
Soft delete by default, forceDelete opt-in	CustomerProvider.Delete
Bulk operations (BulkSave)	CustomerProvider.Import
Query projection (Project)	Logic/Customers/Search/CustomerSearchQueryBuilderRule.cs
ThrowsAnExceptionIfNotExisting / EntityNotFoundException	CustomerProvider.cs, Api/.../EntityNotFoundExceptionTransformation.cs
Auto migration on startup (WebApi:EntityFrameworkMigration:AutoMigrate)	Api/appsettings.json

GerstITS.Data.EntityFramework.SqlServer works exactly like the PostgreSql package: derive from SqlServerDatabaseConfiguratorBase<TDbContext> instead. Note that only one IDatabaseConfigurator implementation is allowed per assembly.

GerstITS.Search

Feature	Example
ISearchEngine + SearchResult<T>	Logic/Customers/CustomerProvider.cs (Search)
SearchFilterBase (paging + sorting)	Logic/Customers/Contracts/CustomerSearchFilter.cs
SearchQueryBuilderRuleBase<TItem, TFilter>	Logic/Customers/Search/CustomerSearchQueryBuilderRule.cs
InitializationRuleBase<T> (filter defaults)	Logic/Customers/Search/CustomerSearchFilterInitializationRule.cs
PagingValidationRuleBase<T>	Logic/Customers/Validation/CustomerSearchFilterValidationRule.cs
Custom ISortingProvider	Logic/Shared/Search/Sorting/SortingProvider.cs

GerstITS.Validation

Feature	Example
ValidationRuleBase<T> (FluentValidation)	Logic/Customers/Validation/CustomerValidationRule.cs, Logic/Shared/Validation/IdValidationRule.cs
IsEMail() rule builder extension	CustomerValidationRule.cs
Automatic validation in fluent controllers (IValidator)	All controllers via FluentApiControllerBase
Explicit validation in minimal API endpoints (IValidator + ToErrorMessage)	Api/Endpoints/Endpoints.Validator.cs

GerstITS.Mapping.AutoMapper

Feature	Example
Profiles + RegisterMappingsOf<T>()	Logic/Customers/Mappings/CustomerMapping.cs, Logic/Example/Mappings/IntegerMapping.cs

GerstITS.Web / GerstITS.Web.Api / GerstITS.Web.Api.Swagger / GerstITS.Web.Rest

Feature	Example
HostingStartup fluent pipeline	Api/Program.cs
FluentApiControllerBase (Api().Use(...).Get/Create/Update/Delete)	Api/Controllers/1.1/*.cs
API versioning (side by side controllers)	Api/Controllers/1.0 vs Api/Controllers/1.1
Minimal API endpoints (partial Endpoints class per feature, nested static endpoint classes)	Api/Endpoints/Endpoints.cs, Endpoints.Customers.cs, Endpoints.CustomerNotes.cs
Endpoint grouping + Swagger tags (MapGroup, WithTags)	Api/Endpoints/Endpoints.Customers.cs
Query parameter binding to search filters ([AsParameters])	Endpoints.Customers.MapSearch
Global exception transformations	Api/Common/ExceptionHandling/Transformations/*.cs
Global exception handling middleware for minimal APIs (UseGlobalExceptionHandling)	Api/Common/ExceptionHandling/Extensions/WebApplicationExtensions.cs, Api/Program.cs
Automatic response compression (zstd, brotli, gzip — also for HTTPS)	built in, no app code required — see "Response compression" below
Server configuration (CORS, HSTS, forwarded headers)	Api/Common/Configurations/WebApiConfiguration.Server.*.cs
Swagger configuration incl. security schemes	Api/Common/Configurations/WebApiConfiguration.Swagger*.cs, WebApiConfiguration.OpenApiSecurityScheme.cs
Session based cache storage (AddHttpSession)	Api/Module.Session.cs, CacheController.cs
Typed REST clients (IWebService, WebMethod, ResourceUrl, HttpHeader)	GerstITS.WebClients.Example.Api/Contracts/ICustomer.cs
RestWebServiceConfigurationBase + creation rules	GerstITS.WebClients.Example.Api/Configurations, CreationRules
IWebClient.Request<T>().Execute(...)	WebClient.Console/Tests/TestRunner.cs

GerstITS.Authentication.ApiKey / GerstITS.Authentication.OpenId

Feature	Example
[ApiKey] attribute + IApiKeyConfiguration	Api/Controllers/1.1/MaintenanceController.cs, WebApiConfiguration.ApiKey.cs
JWT bearer via IOpenIdConfiguration + [Authorize]	Api/Controllers/1.1/SecuredController.cs, WebApiConfiguration.OpenId*.cs

GerstITS.Mail

Feature	Example
IMailProvider, MailNotification, ContactRequest	Api/Controllers/1.1/ContactController.cs
SMTP configuration (Mail section)	Api/appsettings.json

GerstITS.Job / GerstITS.Job.Scheduling

Feature	Example
JobBase + cron scheduling	Jobs.SayHelloWorld/Jobs/*.cs
JobSchedulingConfigurationBase (named + convention based)	Jobs.SayHelloWorld/Configurations/*.cs, Api/appsettings.json (Jobs section)
RegisterJob<TJob, TConfig>() + IgnoreConditions	Jobs.SayHelloWorld/Module.cs

GerstITS.TestFramework

Feature	Example
[TestCategory(TestCategories.Unit/Integration)] traits	GerstITS.Examples.Tests/**/*Test.cs
Filtering: dotnet test --filter "Category=Unit"	see below

Running

1. Database: the API auto-migrates on startup (AutoMigrate: true). Adjust the CustomerDbContext connection string in GerstITS.Examples.Api/appsettings.json (PostgreSQL).
2. API: start GerstITS.Examples.Api. Swagger UI is available in development at /api/swagger.
3. Console client: start GerstITS.Examples.WebClient.Console while the API is running.
4. Tests: dotnet test (optionally --filter "Category=Unit").
5. Migrations: dotnet ef migrations add <Name> inside GerstITS.Examples.Data (uses the design time factory and appsettings.json of that project).

Fluent controllers vs. minimal API endpoints

The customer domain is exposed twice to compare both styles:

• POST/GET/PUT/DELETE /api/Customer — fluent controllers (FluentApiControllerBase, validation and exception transformations applied by the fluent pipeline).
• GET/POST/PUT/DELETE /api/v2.0/customers — minimal API endpoints (partial Endpoints class, explicit Endpoints.Validator, exception transformations applied by UseGlobalExceptionHandling).

Search differs on purpose: the controller uses POST /api/Customer/Search with a body filter, the minimal API uses GET /api/v2.0/customers binding the same CustomerSearchFilter from query parameters via [AsParameters].

Response compression

GerstITS.Web.Api enables response compression automatically — there is nothing to register or configure in the application: the framework module registers the zstd (ZstdSharp), brotli and gzip providers with EnableForHttps = true and HostingStartup...Build() adds the UseResponseCompression() middleware. The provider is picked by the client's Accept-Encoding header (zstd preferred, then brotli, then gzip):

curl -s -D - -o NUL -H "Accept-Encoding: zstd, br, gzip" https://localhost:<port>/api/v2.0/customers

The response then carries the matching Content-Encoding header (e.g. Content-Encoding: zstd).

Requires the first GerstITS.Web.Api release after 2026.7.7 — older packages do not contain the compression feature yet, requests are then answered uncompressed.

Api key protected endpoints

GET /api/Maintenance/Ping requires the header configured under WebApi:ApiKey (default: X-Api-Key: example-api-key).