139 lines
8.7 KiB
Markdown
139 lines
8.7 KiB
Markdown
# 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, 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` |
|
|
|
|
### 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` |
|
|
| Global exception transformations | `Api/Common/ExceptionHandling/Transformations/*.cs` |
|
|
| 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).
|
|
|
|
### Api key protected endpoints
|
|
|
|
`GET /api/Maintenance/Ping` requires the header configured under `WebApi:ApiKey` (default: `X-Api-Key: example-api-key`).
|