Forem: Jani Giannoudis

Payroll Engine: From Open-Source Prototype to Production-Ready

Jani Giannoudis — Sat, 21 Mar 2026 12:57:48 +0000

Two and a half years ago, I introduced Payroll Engine in this series — an open-source payroll calculation framework written in C#. The architecture was in place, regulation layers worked, the first Swiss payroll calculations were running. A working prototype.

A lot has happened since. On the road to version 1.0, I had to answer the question every framework developer eventually faces: What's still missing between "it works" and "it's production-ready"?

The answer was: quite a lot.

Security as the Foundation

A payroll system without robust security is not software — it's a liability. This was the area that demanded the biggest overhaul.

Authentication and Authorization

The backend now supports three configurable authentication modes:

None — for local development and testing
ApiKey — simple header-based authentication with environment variable fallback
OAuth — full OAuth 2.0 integration with configurable authority, audience, and client secret

On startup, the system validates the OAuth configuration to prevent token confusion. This sounds like an edge case, but it's exactly the kind of bug that becomes a disaster in multi-tenant environments.

{
  "Authentication": {
    "Mode": "OAuth",
    "Authority": "https://auth.example.com",
    "Audience": "payroll-api"
  }
}

Script Safety Analysis

Payroll Engine executes C# scripts at runtime — that's the core of its regulation flexibility. But flexibility without control is a security risk. The new Script Safety Analysis statically checks every script for banned API calls:

System.IO — no file access
System.Net — no network access
System.Diagnostics — no process control
System.Reflection — no metaprogramming

The feature is opt-in (ScriptSafetyAnalysis: true) because static analysis slows down compilation. For production environments, however, it's strongly recommended.

Cryptography and Input Validation

Under the hood, SHA1 hashes were replaced with SHA256, combined with constant-time comparisons to prevent timing attacks. Password validation was hardened with regex timeouts against ReDoS attacks. Small changes, but essential in a system handling payroll data.

Scaling: From 10 to 10,000 Employees

The prototype calculated payroll sequentially — employee by employee, synchronously. For a company with 20 employees, that's fine. For one with 10,000, it's a showstopper.

Asynchronous Job Processing

Payrun jobs now run through an asynchronous background queue:

The job is pre-persisted in the database
A bounded channel queue (capacity: 100) provides backpressure
A BackgroundService dequeues and processes jobs
The API call immediately returns HTTP 202 with a location header
A webhook fires on completion or abort

On unhandled exceptions or server shutdown, the job is cleanly aborted — no orphaned state in the database.

Parallel Employee Processing

The new MaxParallelEmployees configuration controls the degree of parallelism:

Value	Behavior
`0` / `off`	Sequential (default)
`half`	Half of available CPU cores
`max` / `-1`	All available cores
`1`–`N`	Explicit count

The key to thread safety was introducing PayrunEmployeeScope — an isolated state envelope per employee. Add thread-safe progress reporting with batched DB persistence (every 10 employees), and a payroll calculator cache using Lazy<T> with a composite key (calendar + culture).

Bulk Operations

For initial onboarding of large tenants, there's now a bulk endpoint:

POST .../employees/bulk

Internally, it uses SqlBulkCopy in 5,000-item chunks. This isn't REST purism — it's pragmatism. Inserting 10,000 employees through individual requests simply isn't practical.

Developer Experience

A framework is only as good as it feels to work with. Three features fundamentally improved the developer experience.

Payrun Job Preview

Perhaps the most useful new feature: a synchronous preview endpoint that runs a payroll calculation for a single employee — without writing anything to the database.

POST .../payruns/jobs/preview
→ PayrollResultSet (wage types, collectors, payrun results)

The preview accepts any RetroPayMode but responds with HTTP 422 if a retroactive calculation would be triggered. This gives developers immediate feedback without touching the dataset — ideal for regulation development and UI integration.

Excel-Based Regulation Import

Regulations could always be imported as JSON exchange files. But not every payroll specialist thinks in JSON. The new Excel import supports all regulation objects:

Cases, case fields, case relations, collectors, wage types, lookups, lookup values, reports, report parameters, report templates, and scripts.

This significantly lowers the barrier to entry for professionals defining regulations.

CI/CD and Docker

The entire release pipeline has been automated:

Wave-based builds — dependencies are built in the correct order
Version guard — prevents accidental overwrites of existing releases
Single-click release — one GitHub Actions workflow for all libraries and applications
Docker images — Backend, Console, and WebApp as Linux containers on ghcr.io/payroll-engine/*
Swagger — auto-generated and attached to every release

A dry-run mode allows testing the pipeline without side effects.

MCP Server

Payroll Engine now ships an MCP Server — a lightweight bridge that exposes the PE REST API as tools for any MCP-compatible AI client (Claude Desktop, Cursor).

The v0.1-preview ships with seven read-only tools: GetTenants, GetEmployees, GetPayrolls, GetPayrunJobs, GetPayrunResults, GetEmployeeCaseValues, and GetWageTypes. Built on the existing Client.Services interfaces, it adds no new business logic — it simply makes the existing API queryable in natural language.

Claude Desktop / WebApp
        │  MCP Protocol (stdio)
        ▼
PayrollEngine.McpServer
        │  PE HTTP Client
        ▼
PayrollEngine Backend (REST API)

Local setup takes one entry in claude_desktop_config.json. Hosted deployment via SSE transport is planned for a later release.

To make this concrete: here's a real session with Claude Desktop against a live payroll database:

Q: What was the gross salary of all employees as of December 31, 2024?
A: (structured list of employees with their wage type results for the period)

Q: What changed in the employee data of mario.nunez in January 2025?
A: (list of case value mutations with effective dates)

Q: What is the tax rate for an income of 85,000 in the TaxRates lookup?
A: (resolved lookup value across all regulation layers — no SQL, no join, no code)

The last example is particularly interesting: the AI resolves the lookup across all stacked regulation layers automatically. There is no configuration required on the client side.

Still early — stdio-only, read-only, no write operations. But already useful enough to change how payroll data is explored during development and support.

Integrated Load Tests

Dedicated load test commands are now built into the Console:

LoadTestGenerate — scales exchange files from any regulation template
LoadTestSetup — imports employees via the bulk API
PayrunLoadTest — executes payruns with warmup, measured repetitions, and CSV report

This enables reproducible performance measurements integrated directly into the development cycle.

Stability: The Invisible Work

No release post is just about new features. The truth is: a large part of the work was finding and fixing bugs that never surface under normal conditions — but lead to catastrophic failures under load or in edge cases.

Some examples:

Inverted filter logic — GetCaseValuesAsync was excluding values matching the requested slot instead of keeping them. The classic off-by-negation bug that doesn't show up in single-slot tests.

Race condition in code cache — CodeFactory.CodeFiles used a Dictionary that corrupted under concurrent access. Replaced with ConcurrentDictionary.

Non-deterministic culture fallback — Payroll calculation used CultureInfo.CurrentCulture, which can vary by thread and server. Now deterministically falls back to en-US.

Sync-over-async in the scripting layer — .Result calls causing deadlocks under load. Replaced with .ConfigureAwait(false).GetAwaiter().GetResult().

Timer leak in assembly cache — Missing thread-safe initialization led to duplicate timers that were never cleaned up.

These aren't glamorous fixes. But they're the difference between "works on my machine" and "works reliably in production."

Additional Improvements

Beyond the core themes, there are several further enhancements:

Rate limiting — configurable limits per endpoint, with a dedicated policy for the payrun start endpoint
CORS configuration — disabled by default, fine-grained configuration available
Granular audit trail — separate controls for Script, Lookup, Input, Payrun, and Report instead of a single toggle
Database collation check — verified on startup before the schema check to prevent silent data integrity issues
Retro payrun limit — MaxRetroPayrunPeriods as a safety net against runaway retroactive calculations
MySQL support — a separate DbContext implementation alongside the existing SQL Server persistence layer, making self-hosted deployments more accessible across different infrastructure environments
Employee timing logs — per-employee duration and summary for performance analysis

What's Next

Payroll Engine 1.0 ships in April 2026. The architecture is stable, the API is solid, and the regulation layer is battle-tested.

The project is open source (MIT license) and targets developers who want to embed payroll functionality into existing HR and ERP systems — not as SaaS, but as a self-hosted framework where payroll logic lives in configurable regulations rather than hardcoded rules.

Links:

Feedback and contributions are welcome. If you have questions about the architecture or integration, open an issue on GitHub or drop a comment below.

High-performance backend scripting for .NET

Jani Giannoudis — Mon, 02 Feb 2026 17:35:34 +0000

The following article presents an approach that allows C# scripts to be executed efficiently in the backend.
This decouples the implementation of the business logic from the backend code.

The following criteria were taken into account when implementing the scripting API:

Performance	Stability	Script development
The scripts are executed at the fastest possible speed to ensure fast response times and reduce the use of infrastructure resources.	The scripts do not affect backend execution.	Comprehensible script syntax and API documentation.

The solution involves dividing the use of backend scripts into two phases: creation and use.

During the creation phase, the script is compiled into an assembly and stored in the database as binary data. This allows syntax or type errors to be identified early on, ensuring that only executable code is fed in.

During the usage phase, the assembly is loaded from the database and executed in a controlled manner within a runtime environment. Unused assemblies are removed from the back-end cache after a certain period of time.

This approach is suitable for	This approach is not suitable for
Computationally intensive backend systems	Ongoing changes to business logic
Financial trading platforms	Highly parallel I/O (real-time)
AI and machine learning services	Microservice architecture
Real-time simulations and CAD systems	Maximum speed to MVP/time-to-market

Application example

This article provides a customisable evaluation of stock quotes based on the StockQuote, StockQuoteScript and StockQuoteResult objects.

The usage consists of the following sequence:

Create stock quotes.
Create evaluation scripts.
Analyze stock quotes.

Note: This application is for illustrative purposes only and should not be used with any production systems.

1. Create Stock Quotes

Use the POST endpoint quotes/mock to create StockQuote mock entries. The count parameter determines the number of entries created.
By default, 2,000 entries are generated.

2. Create evaluation scripts

You can create and update a StockQuoteScript object using the quotes/scripts endpoint.

The following scripts were selected for this example:

Name	Script
Price Volatility	`(PriceRange) / OpenPrice`
Breakaway Check	`(HighPrice <= LowPrice * 1.2m) ? 1 : null`
Intraday Return	`if (OpenPrice == 0) return 0;` `return (ClosePrice - OpenPrice) / OpenPrice`
Typical Price	`HighPrice + LowPrice + ClosePrice) / 3`
Raw Money Flow	`((HighPrice + LowPrice + ClosePrice) / 3) * Volume`
Upper Shadow Percentage	`var maxBody = Math.Max(OpenPrice, ClosePrice);` `return maxBody == 0 ? null : (HighPrice - maxBody) / maxBody`

The evaluation examples can be found in the file StockQuoteScripts.json.

3. Analyze stock quotes

The POST endpoint quotes/scripts/{scriptId}/evaluate starts evaluating a script. The script calculates the value for each StockQuote and stores it as a StockQuoteResult. If the script's result is undefined (null), no result is stored.

The results of the script can be listed using the GET endpointquotes/{quoteId}/scripts/{scriptId}. The durations of the processing steps can be seen in the log file log.txt.

Performance Results

Performance testing was conducted on the following computer:

Processor: Intel Core i7-10875H CPU @ 2.30GHz
RAM: 32 GB
HD: 500 GB SSD
OS: Windows 11 Pro, version 25H2
Database: Microsoft SQL Server 15.0.2155.2
.NET 10.0.102

The following results show the time required to evaluate 100,000 stock quotes:

Script	Load (ms)	Evaluate (ms)	Store (ms) ¹⁾
Price Volatility	102	260	557
Breakaway Check	109	244	335
Intraday Return	113	211	567
Typical Price	107	232	602
Raw Money Flow	88	220	597
Upper Shadow Percentage	86	268	613

The execution times for 1,000,000 stock quotes are as follows:

Script	Load (ms)	Evaluate (ms)	Store (ms) ¹⁾
Price Volatility	1292	2271	6028
Breakaway Check	1000	2096	3612
Intraday Return	988	2259	6520
TypicalPrice	1064	2203	5636
Raw Money Flow	1051	2199	6093
Upper Shadow Percentage	907	2317	5565

¹⁾ The results are stored in bulk.

Conclusion
On average, they demonstrate a consistently high processing speed of 2,500 nanoseconds per stock quote. However, scripts with I/O queries increase processing time.

Backend Implementation

The solution is divided into the following projects:

Model: Stock Quote Object Model.
Scripting with the compiler and scripting runtime/function.
Persistence Database context and repositories.
Server: Stock quote services, DTOs, and endpoints.

Persistence

SQL Server is used to store the data. The stock quote database uses the following model:

The database schema can be generated using the Database/ModelCreate.sql file in the GitHub repository.

The lightweight Dapper is used as the ORM.

The following repositories are available:

StockQuoteRepository: Read, create, and delete stock quotes.
StockQuoteScriptRepository: Read, create, update, and delete stock quote scripts.
- Script compilation takes place when the object is created and updated.
StockQuoteResultRepository: Read, create, and delete stock quote results.
- Due to the large amount of data, stock quote results are generated in bulk mode.

Script Compiler

The script compiler uses Roslyn to generate a .NET assembly for each script.
The assembly's binary data and the script's hash value are stored in the database with the script object.
The hash code is used for assembly caching.

The following example shows how to create a stock quote script using the StockQuoteScriptRepository method AddAsync().

public async Task<int?> AddAsync(StockQuoteScript stockQuoteScript)
{
    const string sql = "INSERT INTO StockQuoteScript(Name, Script, Binary, ScriptHash)" +
                       " VALUES(@Name, @Script, @Binary, @ScriptHash);" +
                       " SELECT CAST(SCOPE_IDENTITY() as int)";

    try
    {
        // script compile: setup binary and script hash
        StockQuoteCompiler.Compile(stockQuoteScript);
    }
    catch (ScriptCompileException exception)
    {
        Log.Error(exception, exception.GetBaseException().Message);
        return null;
    }

    // create quote stock script
    using var connection = DbContext.Create();
    var result = await connection.ExecuteScalarAsync<int>(sql, stockQuoteScript);
    return result;
}

The assembly binary data and the script hash are backend attributes not included in the API DTO.

public sealed record CreateStockQuoteScriptRequest(
    string Name,
    string Script);

Script Runtime

The runtime isolates the script function from the backend and controls the scripting process.

Communication between the runtime and the function occurs via the dynamic object type.
- Basic object types, such as decimal and int, as well as core objects, such as Tuple and List, can be used.
The function has access to the public properties and methods of the runtime class.
The function runs in its own task.
- A Timeout prevents executions from taking too long.

public class StockQuoteRuntime(StockQuote stockQuote, IScriptObject script, TimeSpan timeout)
{
    private StockQuote StockQuote { get; } = stockQuote;
    private IScriptObject Script { get; } = script;
    private TimeSpan Timeout { get; } = timeout;

    // properties
    public string Symbol => StockQuote.Symbol;
    public decimal OpenPrice => StockQuote.OpenPrice;
    public decimal HighPrice => StockQuote.HighPrice;
    public decimal LowPrice => StockQuote.LowPrice;
    public decimal ClosePrice => StockQuote.ClosePrice;
    public long Volume => StockQuote.Volume;
    public double MarketCap => StockQuote.MarketCap;
    public DateTime Timestamp => StockQuote.Timestamp;

    // methods
    public decimal GetYearAveragePrice() =>
        (decimal)Random.Shared.NextDouble() * (HighPrice - LowPrice) + LowPrice;

    public object? Evaluate() => InvokeScript();

    [MethodImpl(MethodImplOptions.NoInlining)]
    private object? InvokeScript()
    {
        try
        {
            var task = Task.Factory.StartNew<decimal?>(() =>
            {
                // create script
                using var script = CreateScript<StockQuoteFunction>(Script);
                // dynamic
                var value = script.Evaluate();
                return value;
            });
            return task.WaitScriptResult(typeof(StockQuoteFunction), Timeout);
        }
        catch (Exception exception)
        {
            throw new ScriptException($"Evaluation error in stock quote {StockQuote.Id}: "+
                                      $"{exception.GetBaseException().Message}.", exception);
        }
    }

    [MethodImpl(MethodImplOptions.NoInlining)]
    private dynamic CreateScript<TFunc>(IScriptObject scriptObject)
    {
        // load assembly
        var scriptType = typeof(TFunc);
        var assembly = AssemblyFactory.GetObjectAssembly(typeof(IScriptObject), scriptObject);
        var assemblyScriptType = assembly.GetType(scriptType.FullName ?? throw new InvalidOperationException());
        if (assemblyScriptType == null)
        {
            throw new ScriptException($"Unknown script type {scriptType}.");
        }

        // script function execution with runtime as constructor argument
        return Activator.CreateInstance(assemblyScriptType, this)!;
    }
}

The attribute MethodImpl(MethodImplOptions.NoInlining) disables inline optimization for scripts.

The following rules must be observed when implementing the scripting runtime:

Query data should be retrieved using keys on indexed database fields.
Values that are queried multiple times from the function should be stored in a runtime cache.

Script Function

The script is embedded in the function class template for compilation.

In the Stock Quote example, the entry point is the Evaluate method, which requires a return value.
Therefore, the Stock Quote script must contain a return statement.

public class StockQuoteFunction : IDisposable
{
    private dynamic Runtime { get; }
    public StockQuoteFunction(object runtime)
    {
        Runtime = runtime ?? throw new ArgumentNullException(nameof(runtime));
    }

    // properties
    public string Symbol => Runtime.Symbol;
    public decimal OpenPrice => Runtime.OpenPrice;
    public decimal HighPrice => Runtime.HighPrice;
    public decimal LowPrice => Runtime.LowPrice;
    public decimal ClosePrice => Runtime.ClosePrice;
    public long Volume => Runtime.Volume;
    public double MarketCap => Runtime.MarketCap;
    public DateTime Timestamp => Runtime.Timestamp;
    public decimal PriceRange => HighPrice - LowPrice;

    // methods
    public decimal GetYearAveragePrice() => Runtime.GetYearAveragePrice();

    public object? Evaluate()
    {
        // script placeholder
        #region Script
        #endregion

        return null;
    }

    public void Dispose() => GC.SuppressFinalize(this);
}

The following is an example of what a validation script could look like:

public class StockValidateFunction : IDisposable
{
    public bool? Validate()
    {
        // script placeholder
        #region Script
        #endregion

        return null;
    }
}

The script function is a template that must be registered as an embedded resource within the C# project file.

<ItemGroup>
  <EmbeddedResource Include="StockQuoteFunction.cs">
      <LogicalName>StockQuoteFunction.cs</LogicalName>
  </EmbeddedResource>
</ItemGroup>

Assembly Factory

The AssemblyFactory class loads and stores assemblies in the backend's memory for a specified period of time.
The retention period is determined by the AssemblyCacheTimeout application setting, which has a default value of 30 minutes. You can disable assembly caching by setting the timeout to zero.

If a cached script changes, you can remove the assembly using the AssemblyFactory.InvalidateObjectAssembly() method. In the stock quote example, this is done in the StockQuoteScriptRepository.UpdateAsync() method.

Scripting Documentation

Users have access to HTML documentation describing the available properties and methods of the script function.
This reference is generated based on the source code XML documentation.

The open-source tool DocFX (https://github.com/dotnet/docfx) was used to generate the documentation.

Steps to use the static HTML documentation:

Run the BackendScripting.Scripting\docfx\Static.Build.cmd command.
Run BackendScripting.Scripting\docfx\Static.Start.cmd to open the HTML start page.

Steps to use the web application:

Start the BackendScripting.Scripting\docfx\Server.Start.cmd command.
Open the URL http://localhost:5865 to access the start page.

Technology

The following .NET and C# features were helpful in implementing this architecture:

Strict type system.
Native support for decimal numbers (decimal).
Shared memory access (dynamic).
An extensible metadata model that can be evaluated using reflection.
Type extensions, such as operator overloading (DSL extensions).
Runtime code generation and compilation with Roslyn.
Asynchronous execution with async/await.
True native threads.
Runtime-managed thread pooling.
Highly optimized scheduling of tasks across CPU cores.
A proven, open-source ASP.NET Core web server platform.

GitHub Repository

This example can be found in the GitHub repository BackendScripting.

The following components are used for illustration purposes:

Serilog for logging.
Bogus for creating mock data.
Dapper as a database object mapper.
DocFx for creating scripting documentation.

Outlook

This low-code approach paves the way for automatically converting no-code or DSL instructions into C# backend scripts.

Create a timesheet-based Payroll Application

Jani Giannoudis — Thu, 27 Mar 2025 10:05:42 +0000

This article describes how the Payroll Engine is used to develop a payroll solution based on a variable timesheet.
The Payroll Engine is an open source project that enables the development of scalable cloud payroll solutions.

The following requirements were considered:

Support for different payroll periods: weekly, bi-weekly, monthly, bi-monthly, etc.
Wage factor for casual workers.
Variable daily rates divided into regular working hours and early/late periods.
Parallel use of timesheets with different working time models.
Timesheet data can be changed daily, scheduled and time limited.
Customization of wage calculation with individual additional rates and factors.
Automated payroll testing.
Definition of special days (public holidays, trade fair, etc.).
Integration of external working hours from Excel documents.
Report on employee working hours and wages by period.

Use Cases

The application covers the following use cases:

Timesheet: Configure timesheet
Employment: Manage employee employment
Work Time: Record employee work time
Payrun: Perform wage calculation
Wage Report: Create employee wage document
Work Time Report: Create employee working time report

Working times are recorded by the employee themselves (self-service) or by the HR user.

Timesheet

The timesheet describes the working time and basic wage data:

Field	Description	Value type
`StartTime`	Regular period start time	Hour
`EndTime`	Regular period end time	Hour
`MinWorkTime`	Minimum work time	Hour
`MaxWorkTime`	Maximum work time	Hour
`BreakMin`	Minimum break time	Minute
`BreakMax`	Maximum break time	Minute
`RegularRate`	Regular hour rate	Money
`CasualRateFactor`	Casual worker factor to the regular rate	Percent

Time Periods

In the timesheet, the working day is divided into different time periods:

Regular period: Start and end of the working day and pay rates
Early periods: Working periods from midnight to the start of regular working hours
Late periods: Working periods after the regular working time until midnight

The periods are arranged according to the sort key next to the standard working time. Negative sort values apply to early periods and positive sort values to late periods.

The following standard fields exist for each period:

Field	Description	Value type
`<Name>Duration`	Period duration	Hour
`<Name>Factor`	Period rate factor	Percent

Work Time

The employee's working time is defined in the WorkTime object with the following standard fields:

Field	Description	Value type
`WorkTimeDate`	Working day	Date
`WorkTimeStart`	Start hour	Hour
`WorkTimeEnd`	End hour	Hour
`WorkTimeBreak`	Break time	Minute
`WorkTimeHours`	Working hours (calculated)	Minute

Wage Calculation

To calculate the daily wage, the average working time is divided into different periods. The period wage is calculated according to the duration of work within the period and the wage factors. The total daily wage is calculated from the wage of the regular working time and all early and late periods.

The following example shows the distribution of the employee's working time between the daily periods. The employee has worked from 9.00 to 20.00 with a break of 30 minutes:

Application Usage

The use cases are executed in the Payroll Engine web application:

First, the timesheet is defined using the Timesheet use case and the employee's employment type is defined using the Employment use case. The employee's working and break times are then recorded using the Work Time use case:

Break times are optional and can be hidden. Authorized users can also run these cases for forecast scenarios.
When a pay run job is executed, the payroll data for the employees is created and saved as Payroll Results.

The employees' working times and the payroll results can be downloaded in various formats (pdf, excel, json, xml).

Special days import

Special days, such as public holidays to be excluded or weekend days to be included, such as trade fairs, are managed in the Workday lookup. The special days can also be imported from an Excel file using the Payroll Console (see example Lookup/Workday/Workdays.2025.xlsx).

Working hours import

For employees who do not have online access, the Payroll Console can also be used to import the working times of employees who have Online (see example Case.Data/WorkingTimes.2025.Week8.xlsx).

Implementation

Tenant Setup

The payroll calendar, which determines the payroll cycle and the regular working days, is defined in the client. The users are assigned to divisions. The calendar determines the payroll cycle and the working days. Employees, who are also entered as users, can record and query their working time.

The payroll data is managed in the regulation object:

Lookup tables such as the special days.
Cases and their fields, which define the data model.
Wage types and collectors for the wage run.
Evaluation with reports.

👉 Tenants can be imported and updated as Json with the Payroll Console (see Wiki Basic Payroll).

Timesheet Scripting

A timesheet is defined by deriving the Timesheet class. The timesheet periods are listed as members of the class and marked with the TimesheetPeriod attribute. This determines whether it is an early or late shift and the order in which they are listed. The attribute parameter ns stands for namespace and is used as a prefix for the case fields of the periods.

public class MyTimesheet : Timesheet
{
    // case fields EarlyPeriodDuration and EarlyPeriodFactor
    [TimesheetPeriod(order: -1, ns: nameof(EarlyPeriod))]
    public TimesheetPeriod EarlyPeriod { get; } = new();

    // case fields LatePeriodLowDuration and LatePeriodLowFactor
    [TimesheetPeriod(order: +1, ns: nameof(LatePeriodLow))]
    public TimesheetPeriod LatePeriodLow { get; } = new();

    // case fields LatePeriodHighDuration and LatePeriodHighFactor
    [TimesheetPeriod(order: +2, ns: nameof(LatePeriodHigh))]
    public TimesheetPeriod LatePeriodHigh { get; } = new();
}

In the following example, an additional field WeekendRateFactor is added to the timesheet to allow for an additional surcharge on weekend days.

public class MyTimesheet : Timesheet
{
    // case fields LatePeriodDuration and LatePeriodFactor
    [TimesheetPeriod(order: +1, ns: nameof(LatePeriod))]
    public TimesheetPeriod LatePeriod { get; } = new();

    // case field WeekendRateFactor
    public decimal WeekendRateFactor { get; set; }
}

User-defined wage calculation

A derivative of the TimesheetCalculator class is implemented for the wage calculation. The CalcRegularWage method takes into account the additional weekend factor in the wage calculation:

public class MyTimesheetCalculator : TimesheetCalculator<MyTimesheet>
{
    protected override decimal CalcRegularWage(WageDay day, HourPeriod timesheetPeriod)
    {
        // regular wage
        var wage = base.CalcRegularWage(day, timesheetPeriod);

        // weekend factor
        if (day.Date.DayOfWeek is DayOfWeek.Saturday or DayOfWeek.Sunday)
        {
            wage *= (1m + day.Timesheet.WeekendRateFactor);
        }
        return wage;
    }
}

The WeekDay parameter contains the daily values of the timesheet, the employment type and the daily working time.

Multiple Timesheets

To use multiple timesheets, the namespace can be defined with the CaseObject attribute:

[CaseObject(ns: "Int")]
public class IntTimesheet : Timesheet
{
    // case fields IntEarlyPeriodDuration and IntEarlyPeriodFactor
    [TimesheetPeriod(order: -1, ns: nameof(EarlyPeriod))]
    public TimesheetPeriod EarlyPeriod { get; } = new();

    // case fields IntLatePeriodDuration and IntLatePeriodFactor
    [TimesheetPeriod(order: +1, ns: nameof(LatePeriod))]
    public TimesheetPeriod LatePeriod { get; } = new();
}

[CaseObject(ns: "Ext")]
public class ExtTimesheet : Timesheet
{
    // case fields ExtEarlyPeriodDuration and ExtEarlyPeriodFactor
    [TimesheetPeriod(order: -1, ns: nameof(EarlyPeriod))]
    public TimesheetPeriod EarlyPeriod { get; } = new();

    // case fields ExtLatePeriodDuration and ExtLatePeriodFactor
    [TimesheetPeriod(order: +1, ns: nameof(LatePeriod))]
    public TimesheetPeriod LatePeriod { get; } = new();
}

Scripting

The scripts in the Payroll Engine are used to control the runtime behavior and are executed on the Backerd server.

Case Scripting

For cases, scripts can be used to control file input (Case Build) and data storage (Case Validate). The Cases worksheet contains the following scripts:

The following script checks the data in the Timesheet case:

public static bool Validate<TTimesheet>(CaseValidateFunction function)
    where TTimesheet : Timesheet, new()
{
    var workday = function.GetChangeCaseObject<TTimesheet>();

    // retro changes
    if (!function.AdminUser)
    {
        var start = function.GetStart(nameof(Timesheet.RegularRate));
        var period = function.GetCalendarPeriod();
        if (start.HasValue && period.IsBefore(start.Value))
        {
            function.AddIssue($"Timesheet change date {start.Value:d} is before calendar start {period.Start:d}");
            return true;
        }
    }

    // regular work time
    var workTime = workday.EndTime - workday.StartTime;
    if (workTime <= 0)
    {
        function.AddIssue("Missing timesheet regular duration.");
        return true;
    }
    if (workday.MaxWorkTime < workday.MinWorkTime)
    {
        function.AddIssue("Invalid working time maximum.");
        return true;
    }

    // break
    if (workday.BreakMax / 60 >= workTime)
    {
        function.AddIssue("Break time maximum must be less than the regular working time.");
        return true;
    }
    if (workday.BreakMax < workday.BreakMin)
    {
        function.AddIssue("Invalid break time maximum.");
        return true;
    }

    // time step
    if (workday.WorkTimeStep is < 1 or > 30)
    {
        function.AddIssue("Invalid working time step size.");
        return true;
    }
    if (60m % workday.WorkTimeStep != 0)
    {
        function.AddIssue("Working time step must be a part of 60 minutes.");
        return true;
    }

    // start/end date
    function.UpdateStart(function.GetStart("RegularRate"));
    function.UpdateEnd(function.GetEnd("RegularRate"));
    return true;
}

The script checks the following aspects of the timesheet (areas):

retro changes: No time recording outside the working period, which can be overridden by the administrator.
regular work time: Valid limits of the regular work time.
break: Valid break time limits.
time step: Valid step size for the input accuracy.
start/end date: Ensures that all timesheet fields apply to the same period.

The timesheet case functions are located in the classes Timesheet/CaseBuild.cs and Timesheet/CaseValidate.cs.

Wage Type Scripting

The calculation of wages is divided into wage types, which are processed in numerical order. To display wages for different periods, a wage type is assigned to each period:

The timesheet wage type functions are located in the classes Timesheet/WageTypeValue.cs.

Report Scripting

In reports, the scripts control the file input (Report Build) and the document generation (Report End).

The Timesheet Wage Type functions are located in the classes Timesheet/ReportBuild.cs and Timesheet/ReportEnd.cs.

Local Development

The Payroll Engine provides the ability to develop and debug case and report scripts locally. Based on the PayrolLEngine.Client.Services, the backend runtime environment is mapped locally. This requires the Payroll Engine API to be available:

Testing

This example includes two tests on different employees. The tests Test/Test.Employee1.pecmd and Test/Test.Employee2.pecmd are run from the Payroll Console:

create a test copy of the employee (name test n), which will be used in the following.
run the Work Time case for 5 working days.
run the payroll for this week.
check the values of the wage types and collectors.

The timing of use cases and payload runs can be freely defined to reflect past or future test scenarios.

👉 Read more about Payroll Testing.

Installation

To use the timesheet application, the Payroll Engine must be installed locally:

Download, install and run the backend API.
Install the timesheet payroll (folder Examples/TimesheetPayroll).
Run the timesheet use cases
- in the web application (uires the web app server to be started).
- with the Payroll Console (Json documents).

More information:
👉 Payroll Engine Wiki

👉 ReadMe TimesheetPayroll

👉 Payroll Engine Client Service NuGet

Introducing Payroll Engine

Jani Giannoudis — Thu, 21 Sep 2023 08:32:01 +0000

Payroll Engine is a multi-client payroll solution designed for use in different industries and countries. The software is aimed at payroll service providers and companies that need to comply with various regulations and rules. As an API-first cloud solution, Payroll Engine is the central source of payroll data and can be embedded into HR and ERP software.

The engine was designed with the following goals in mind.

HR and Employee - Always up-to-date employee data and fault-tolerant data collection with special case coverage.
Payroll Management - Continuous payroll and forecasting for predictive analytics.
Development and Implementation - Payroll professionals can independently develop and test the payroll application.
Partners and Peripheral Systems - Continuous integration of third-party data, such as tax and insurance data, and reporting of employee wages to government and partners.

Payroll Application

To achieve the desired flexibility, the software is divided into two areas.

Backend server with the basic services for calculating and storing payroll data.
Regulations as payroll applications that are executed by the backend server at runtime.

👉 > The article Building Domain Frameworks for Business Applications describes the implementation of this architectural model.

Backend Server

The backend server provides the model for collecting payroll data and divides the Tenant into Divisions for which Payroll is performed. Each Employee is assigned to one or more Divisions and can receive multiple pay slips per work period.

Regulations

The isolated payroll logic is managed as a regulation, a software module that collects, calculates, and reports payroll data.

Runtime behavior is controlled with Low-Code in C# and No-Code with Actions. Clusters provide an advanced tagging mechanism for grouping and filtering the regulation objects.

👉 See the article No-Code and Low-Code for Payroll Software Development for more details on payroll automation.

Like image or CAD layers, regulations can be stacked in the Payroll. The sum of all regulation layers forms the virtual image of the payroll application. Following the principles of object orientation, overlay regulation layers can use, adapt and extend the objects and data of the underlying layers.

Regulations can be shared across divisions and tenants.

The structured design of the regulation layers enables centralized management and distribution of regulations and avoids data redundancy. Without affecting production data, future developments are carried out in additional regulations in a development payroll.

Payroll Services

Payroll services are divided into three areas:

Setup regulation development and tenant onboarding.
Daily business recording employee and company cases.
Payroll managing payroll runs.

The data stored in each area is assigned to a time calendar.

The Culture Calendar controls the date and number format, including the currency. The Payroll Calendar determines the pay cycle and pay period and how years, months and weeks are handled.

Based on the calendar, phase information is handled differently:

Regulations are valid from the start date of the payroll period and cannot be changed during this period (Payroll Calendar).
Case values are kept as time values for which the validity period is determined (Culture calendar).
Payroll results are assigned to a specific payroll period (Payroll calendar).

👉 The handling of time data is described in the article Travel through Time Data.

Regulation Development

The web application provides a regulation editor that takes into account payroll layers.

Regulation Testing

Regulation testing is performed using the console application with the following areas of testing.

Cases: availability, composition, and validation.
Payroll
- Collectors, wage types and user-defined results
- Retroactive results
- Multiple employees and pay periods
Report generation data

Automated business case testing enables test-driven development.

Case Management

When entering employee and business cases, the validity period is determined in addition to the value. This allows retroactive and future changes, as well as the unlimited undo of previous changes.

👉 For an introduction to the use case driven approach, see the article Use Case Driven Development with Low-Code.

Payroll Management

Payroll can be run at any time using the case values that affect the run period. Retroactive changes are detected and values are recalculated up to the current period.

Legal forecasts are multi-level and can be run more than once per payroll period. Only one legal forecast can be active per payroll period. Forecast payroll runs are unlimited and include case values entered for the current forecast.

Technologies Used

The following technologies are used.

The backend server requires a SQL Server database and runs on Linux and Windows. The web and console application also run on Linux and Windows.

Open-Source Project

The Payroll Engine is an Open Source project (MIT license) and is currently in pre-release.

👉 Feedback and contributions are welcome.
👉 More information on the Payroll Engine GitHub Wiki.

Service Registration and Decoration in ASP.NET Core

Jani Giannoudis — Wed, 20 Sep 2023 09:29:57 +0000

Services are the foundation of every ASP.NET Core application and are used through dependency injection. As an application grows, managing services becomes more complex and time-consuming. The following approach uses .NET Reflection to automatically register and decorate services.

Service registration improves the maintainability and extensibility of the software. It allows an existing service to be replaced by a service with additional functionality without having to change it. Examples include caching of data, pre- or post-processing of data, or switching between different implementation variants.

Setup

To use this tool, you must have the ServiceRegistration.NET NuGet package installed.

> dotnet add package ServiceRegistration.NET

// Program.cs
using ServiceRegistration.Service;
...
builder.Services.RegisterServices();
...

Service Registration

The ServiceSingleton, ServiceScoped, and ServiceTransient attributes are used to define the service interface in the service implementation. The attribute correlates with the lifetime of the .NET dependency injection.

For decorators with multiple interface declarations, the IRepository<User> service type must be explicitly specified.

[ServiceTransient(IRepository<User>)]
public class UserRepository : IRepository<User>, IDisposable
{
  ...
}

Service Decoration

The ServiceDecorator attribute is used to specify the type of UserRepository to decorate in the UserCacheRepository decorator class. When the service is registered, the following steps are performed in the DI:

Register the type of UserRepository to decorate.
Register the service decorator IServiceDecorator<UserRepository> with ServiceDecorator<UserRepository>.
Replace the IRepository<User> service registration of UserRepository with UserCacheRepository.

The ServiceDecorator<T> is a proxy type for the decorated type, available through the Implementation property.

Decoration can be applied to types that have a Service* attribute, or be a service decorator itself for nested scenarios. The lifecycle of registered services is determined by the service attribute.

With the extension method IServiceCollection.DecorateService<TService, TDecorator, TComponent> it is possible to decorate a service by code.

// Program.cs
using ServiceRegistration.Service;
...
builder.Services.DecorateService<IRepository<User>,
                                 UserCacheRepository,
                                 UserRepository>();
...

Registration Options

Service registration can be controlled using several options.

Filter the reflection scan for assemblies and assembly types.
Resolve service registration conflicts.
Customize the target registration type.

By default, all assemblies of the current domain are scanned, which can be restricted using the AssemblyFilter. Types are restricted using the TypeFilter, where types with the ServiceIgnore attribute are generally ignored. In the following example, only IRepository service types are registered.

builder.Services.RegisterServices(new()
{
  TypeFilter = type => 
     type.GetInterfaces().Any(x =>
       x.IsGenericType &&
       x.GetGenericTypeDefinition() == typeof(IRepository<>))
});

If there are multiple registrations for a service, the conflicts must be resolved with the ResolveRegistration function or a runtime error will occur.

builder.Services.RegisterServices(new()
{
    ResolveRegistration = (type, filetime, conflicts) =>
                      conflicts.Last() // custom conflict resolve
});

Before the services are registered in the DI, the MapRegistration function provides the ability to customize the type registrations.

builder.Services.RegisterServices(new()
{
    MapRegistration = registration =>
      registration.ImplementationType // custom registation mapping
});

License and Download

The project is licensed under the MIT License and hosted on GitHub.
NuGet package ServiceRegistration.NET

Power your .NET REST API with data queries and reports

Jani Giannoudis — Wed, 06 Sep 2023 18:11:59 +0000

As REST APIs become more centralized sources of information, the need for flexible reporting on REST API data increases. The Reporting API extends an existing REST API so that its data can be analyzed in an easy-to-use reporting tool.

For a project with an extensive REST API, I developed a solution to query the GET endpoint data according to a consistent schema.

The API developer specifies which GET endpoints are available for reporting.
The user can browse, filter, sort, and convert the data to various formats in the UI.
Complex queries with linked data reports can be implemented in a single report.

The Reporting API includes an endpoint that acts as a proxy between queries and GET endpoints. New GET endpoints can be evaluated without further customization. A single model schema is provided to ensure that all queries can be accessed through the same endpoint. The Reporting API uses the ReportDataSet for this purpose, which is compatible with the ADO.NET DataSet and can be serialized for transmission.

The following illustration shows the flow of a request to the GetWeatherForecast endpoint.

1. Retrieving the Metadata

In the first step, the API client queries the available GET methods with the GetQueries endpoint. The return value includes all methods with their query parameters.

2. Entering the Query Parameters

The user defines the query parameters and executes the query using the ExecuteQuery reporting endpoint and the parameter with the target method, for example, GetWeatherForecast.

3. Executing the Query

DI is used to instantiate the desired controller (WeatherForecastController) and execute the GetWeatherForecast method. This is done in the ControllerContext of the ExecuteQuery request to prevent unwanted access. The return value of the method is a list of type WeatherForecast, returned as a ReportingDataSet.

4. Analyzing the Query Data

The API client application can convert the ReportingDataSet to an ADO.NET DataSet, which allows for tabular analysis and format conversions.

👉 Using Reflection to evaluate data takes longer than using direct object access. Reports that need to process large amounts of data should obtain the data through special services.

Enabling Reporting on Your REST API

There are three steps to adding reporting to your REST API.

Step 1 - NuGet

Install the library using the NuGet package.

> dotnet add package RestApiReporting.NET

Step 2 - Reporting Controller

Add the ReportingController.cs file to your API controllers.

using RestApiReporting.Service;
public class ReportingController : ReportingControllerBase
{
    public ReportingController(IApiReportingService reportingService) :
        base(reportingService)
    {
    }
}

Step 3- Reporting Service

// Program.cs
using RestApiReporting.Service;
...
builder.Services.AddReporting();
...

👉 If only the query endpoints are to be available, the controller is derived from the ReportingQueryControllerBase class and the service is registered with Builder.Services.AddReportingQuery().

Now the REST API includes the reporting controller service and can be started.

Customizing the Reporting Service

By default, all GET endpoints are registered as queries. Classes that implement the IReport will register as reports.
The behavior can be controlled using QueryFilter and ReportFilter.
Filtering is controlled at the following levels

Query: assembly, type and method
Report: assembly and type

The ReportingAttribute and ReportingIgnoreAttribute marker attributes provide the ability to include or exclude assemblies, types and methods. Assemblies, types and methods with the ReportingIgnoreAttribute are always ignored. The ReportingAttribute can be used to control reflection in two ways.

In Exclude mode all unwanted endpoints are excluded.

builder.Services.AddReporting(
    new QueryFilter(
        methodFilter: method => !method.IsReporting()));

In Include Mode, only the desired endpoints are captured.

builder.Services.AddReporting(
    new QueryFilter(
        typeFilter: type => type.IsReporting()));

Start the REST API

Once the Reporting Controller is registered with the REST API, it can be launched. Here is how to start the included WebApi REST API sample.

dotnet run --project WebApi\WebApi.csproj --urls=https://localhost:7082

The Reporting Controller appears in Swagger at the URL https://localhost:7082.

Reporting Web Application

The Reporting Web Application is a Blazor server application and requires the REST API URL parameter at startup. In the following example, the Reporting Web Application is launched with the URL https://localhost:8036 and executes the queries and reports via REST with the URL https://localhost:7082 using the --api parameter.

dotnet run --project %~dp0WebApp\WebApp.csproj --urls=https://localhost:8036 --api=https://localhost:7082

After that, the web application can be opened in the browser at https://localhost:8036 and two pages will appear.

Query page - execute the REST API query methods
Report page - build predefined reports

Query Page

This page allows you to execute all query methods.

Queries always have a single result table. This is also true for GET endpoints, which return a single object.

Report Page

The report page allows you to build reports.

👉 Reports can contain data in multiple tables that are related to each other.

Customizing the Web Application

The web application settings are defined in the appsettings.json file.

Setting	Description	Default
`ApiUrl`	API URL such as https://localhost:7161	x
`AppTitle`	Application title	system
`LayoutMode`	Page layout mode: `ExtraSmall`, `Small`, `Medium`, `Large`, `ExtraLarge` or `ExtraExtraLarge`	`Large`
`NameFormat`	Name formatting style: `None`, `PascalSentence` or `CamelSentence`	`PascalSentence`
`DenseMode`	Grid dense mode	`false`
`DataPageCount`	Grid rows per page	`10`
`FilterMode`	Grid filter mode: `Simple`, `Menu`, `Menu`, `Menu`, `Menu` or `Row`	`Simple`

👉 In development mode, it is recommended that you outsource endpoint configuration to User Secrets.

Reports

The report is a C# class that implements the IReport interface.

public interface IReport
{
    string Name { get; }
    string? Description { get; }
    IList<string>? SupportedCultures { get; }
    IList<ApiMethodParameter>? Parameters { get; }
    Task<ReportResponse> BuildAsync(IApiQueryService queryService, 
                                    ReportRequest request);
}

The report has a name, description, culture information, and report parameters. The report is built using the BuildAsync method.

👉 The type for the report parameter ApiMethodParameter is identical to the method parameter of the query methods.

The following example generates the report for a client and its employees.

public class TenantEmployeeReport : IReport
{
    public string Name => "TenantEmployee";
    public string? Description => "Employees by tenant";
    public IList<string>? SupportedCultures => null;
    public IList<ApiMethodParameter>? Parameters => null;

    public async Task<ReportResponse> BuildAsync(
        IApiQueryService queryService, ReportRequest request)
    {
        // tenants
        var tenants = await queryService.QueryAsync(
            new ReportQuery(
                controllerContext: request.ControllerContext,
                methodName: "GetTenants",
                primaryKey: "Id"));
        if (tenants == null)
        {
            return new ReportResponse(request);
        }

        // employees
        var employees = await queryService.QueryAsync(
            new ReportQuery(
                controllerContext: request.ControllerContext,
                methodName: "GetEmployees",
                primaryKey: "Id",
                parameters: request.Parameters));
        if (employees == null)
        {
            return new ReportResponse(request);
        }

        // data set
        var dataSet = new ReportDataSet(nameof(TenantEmployeeReport));
        dataSet.Tables.Add(tenants.ToReportDataTable());
        dataSet.Tables.Add(employees.ToReportDataTable());
        dataSet.Relations.Add(new()
        {
            Name = Name,
            ParentTable = tenants.TableName,
            ParentColumn = "Id",
            ChildTable = employees.TableName,
            ChildColumn = "TenantId"
        });

        return new ReportResponse(dataSet, request);
    }
}

The ability to convert generic IEnumerable collections to tables allows you to merge the results of queries and custom services into a single dataset.

Source Code and NuGet

👉 Source code on GitHub
👉 Package on NuGet

Data-driven Localization for .NET REST APIs

Jani Giannoudis — Mon, 28 Aug 2023 09:43:51 +0000

Because of the high level of automation in the cloud, software models and data are becoming increasingly dynamic. Let's take the example of an online fruit shop that sells its products in several countries. New products are entered by users in different languages.

When designing REST APIs with localized model data, the following considerations must be taken into account

What languages need to be supported?
What data needs to be localized (text, numbers, images, etc.)?
Which endpoints will be required to manage the localized objects?
Which endpoints will deliver the localized data?
How will the localized data be managed in relational database systems?

Scalable REST APIs separate information into translatable and readable data. Model data management endpoints contain all localization data. Within the online store endpoints, the data is delivered in a specific language. This saves resources and often provides ensures that not all information is distributed in all languages.

In addition to data localization, the following considerations are also important for REST APIs that rely on cultural settings to convert numeric, currency, and date data.

REST API product localization:

The REST client identifies available cultures.
Products are captured and submitted in multiple languages.
The REST client requests the products in a specific language as a query string, HTTP request header, or cookie.
The REST API returns the localized product data.

NuGet Package

To use the localization features described here, the NuGet package RestApiLocalization.NET must be installed. The package includes the management of supported system cultures (Culture Provider) as well as the extension methods for localizing data.

Culture - The Localization Foundation

NET cultures have a unique name according to the rules of RFC4646/ISO639/ISO3166, which defines three levels for determining the culture:

The languages registered in the Windows system can be selected according to the following criteria:

Neutral culture such as en or de.
Specific culture such as en-US or de-DE.
Installed culture, which is installed on the REST API computer.
Custom custom user cultures.
Replacement culture for replaced default cultures.

Read mote about the .NET Culture Types.

Culture Provider

The system culture functions are specified in the ICultureProvider interface and provide the ability to limit the available cultures and control the working culture when processing API requests.

public interface ICultureProvider
{
    /// <summary>Get the default culture name</summary>
    string DefaultCultureName { get; }

    /// <summary>Get the current culture</summary>
    CultureInfo CurrentCulture { get; }

   /// <summary>Get the current UI culture</summary>
    CultureInfo CurrentUICulture { get; }

    /// <summary>Set the current application und UI culture</summary>
    void SetCurrentCulture(string cultureName);

    /// <summary>Get the culture by name</summary>
    CultureInfo? GetCulture(string cultureName);

    /// <summary>Get the supported cultures</summary>
    IList<CultureInfo> GetSupportedCultures();

    /// <summary>Get the supported culture descriptions</summary>
    IList<CultureDescription> GetSupportedCultureDescriptions();
}

In the REST application, the localization service is set up at startup.

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);
    ...

    // localization
    builder.Services.AddLocalization(
        cultureScope: new(
            neutral: true,
            specific: true,
            installed: true,
            custom: false,
            replacement: false),
        supportedCultures: new[]
            {
                "en", "en-US", "en-GB",
                "de", "de-DE", "de-AT", "de-CH",
                "zh",
            },
        defaultCulture: "en-US");

    var app = builder.Build();
    ...
}


The `CultureScope` basically defines which system cultures are available. These can be further restricted with the `SupportedCultures`. Restricting the available cultures makes sense if it is known in advance into which languages the data can be localized. For generic REST APIs, where it is not known into which languages the data will be translated, this restriction is not necessary.

> The Culture Provider contains all the information required for ASP.NET Core localization [Request Localization](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/localization/select-language-culture).

The Culture Provider is registered as a singleton in the DI and can be used in the REST API controller to serve information from the Culture API:

csharp
[ApiController]
[Route("cultures")]
public class CulturesController : ControllerBase
{
private ICultureProvider CultureProvider { get; }
public CulturesController(ICultureProvider cultureProvider)
{
CultureProvider = cultureProvider;
}

[HttpGet(Name = "GetCultures")]
public IEnumerable<string> GetCultures() =>
    CultureProvider.GetSupportedCultures()
        .Select(x => x.Name).ToList();

[HttpGet("description", Name = "GetCultureDescriptions")]
public IEnumerable<CultureDescription> GetCultureDescriptions() =>
    CultureProvider.GetSupportedCultureDescriptions();

}


This example returns the list of culture names with `GetCultures` and the list of readable descriptions in English and native with the `GetCultureDescriptions` endpoint.

## Data Localization
The localization is based on the convention of a C# class property. The localization is stored as a string/value dictionary in a property named `<PropertyName>Localizations`. The sample product localizes the `Name` property with `NameLocalizations` and the `Price` property with `PriceLocalizations`.
![Object Localization](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/smlheal8e6sjvy7f6obp.png)

## Localization Extension Methods
The localizations library contains several extension methods for object localization.

csharp
/// Test if localization property exists
bool IsLocalizable(this Type type, string propertyName);

/// Get the property localization values
Dictionary GetLocalizations(
this TObject obj, string propertyName);

/// Get an optional localized property value
object? GetOptionalLocalization(
this TObject obj, string propertyName, string? culture = null);

/// Get an optional localized property value
TValue? GetOptionalLocalization(
this TObject obj, string propertyName, string? culture = null);

/// Get the localized property value
TValue GetLocalization(
this TObject obj, string propertyName, string? culture = null);

/// Map all source object localized values to the target object base properties
TTarget MapLocalizations(
this TTarget target, TSource source, string? culture = null);

/// Map a source object localized value to the target object base property
void MapLocalization(
this TTarget target, TSource source, string propertyName,
string? culture = null)


### Product Localization
The following products are available for the Fruit Online Store.

json
[
{
"name": "Nectarine",
"nameLocalizations": {
"en": "Nectarine",
"de": "Nektarine",
"zh-CN": "油桃"
},
"price": 0,
"priceLocalizations": {
"en": 3,
"de": 3.6,
"de-CH": 3.9,
"zh-CN": 2.8
}
},
{
"name": "GoldenMelon",
"nameLocalizations": {
"en": "Golden Melon",
"de": "Honigmelone",
"zh-CN": "金瓜"
},
"price": 0,
"priceLocalizations": {
"en": 4.5,
"de": 5.7,
"de-CH": 6.2,
"zh-CN": 4
}
}
]


The product is described by the following DTO:

csharp
public class ProductDto
{
public string Name { get; set; } = string.Empty;
public decimal Price { get; set; }
}


In the product controller, the `GetProducts` endpoint returns the localizable products and the `GetProductsDto` method returns the DTOs for the store.

csharp
[ApiController]
[Route("products")]
public class ProductsController : ControllerBase
{

[HttpGet(Name = "GetProducts")]
public IEnumerable<Product> GetProducts()
{
    var products = new ProductService().GetProducts();
    return products;
}

[HttpGet("dto", Name = "GetProductsDto")]
public IEnumerable<ProductDto> GetProductsDto(
    [FromQuery] string? culture = null)
{
    // map products to dto objects
    var config = new MapperConfiguration(
        cfg => cfg.CreateMap<Product, ProductDto>());
    var mapper = new Mapper(config);

    var products = new ProductService().GetProducts();
    var dataProducts = products.ConvertAll(
        // map object
        x => mapper.Map<ProductDto>(x)
            // map localizations
            .MapLocalizations(x, culture)).ToList();
    return dataProducts;
}

}


To convert the product to the DTO, the object is first mapped with [AutoMapper](https://github.com/AutoMapper/AutoMapper) `mapper.Map<ProductDto>` and then `MapLocalizations()` is used to apply the localization to the DTO.

The REST API of this example can be started with the Visual Studio solution `ObjectLocalization.WebApi.sln`.
![Localization REST API](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rzxjtdw0ypfs359p23ui.png)

> To keep the example simple, the products are stored in local JSON files.

## Blazor Client Application
To illustrate localization in clients, there is a Blazor application that uses the open source [MudBlazor](https://github.com/MudBlazor/MudBlazor) UI framework.

The application lists the available languages of the REST API on the `Cultures` page.
![Localization App Cultures](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/x50viuvs7ukllj82cntq.png)

The `Products` page lists the products, including all translations, as well as the DTOs listed.
![Localization App Products](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/14jw8bhbm5emd0po90uo.png)

The DTO product adapts accordingly as the `Culture` changes.

## Relational Persistence of Localization Data
Localized data can be implemented in relational databases in several ways:
- `Table`: The localizations are maintained in a separate table.
- `Column`: The localizations are managed as JSON in an additional column.

Which variant makes sense depends on several factors
- Are the localizations indexable (performance) -> Table
- Is the localization addressable (model references) -> Table
- Is the localization searchable (REST requests) -> Table (simple) or Column (complex)
- Should the localized object remain compact (audits) -> Column
- Should the data model be kept as simple as possible -> Column

### Localization Tables
This variant creates a localization table for each localizable field.
![Localization ERD](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pvd8z1o2aa2ci8jg1in3.png)

### Localization Column
When localized data is stored in an additional column, it is serialized as JSON.
![Localization ERD Minimal](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/urz074i16mv9x1epmxxj.png)

Most ORM tools provide the ability to serialize dictionaries in a field.

#### Entity Framework Code First Localization
Use the [NotMapped](https://learn.microsoft.com/en-us/ef/core/modeling/entity-properties) attribute with an additional string field that contains the serialized JSON.

csharp
using System.Text.Json;
public class Product
{
public string Name { get; set; }
[NotMapped]
public Dictionary NameLocalizations { get; set; }
public string NameLocalizationsJson
{
get => JsonSerializer.
Serialize>(NameLocalizations);
set => NameLocalizations = JsonSerializer.
Deserialize(value);
}

public decimal Price { get; set; }
[NotMapped]
public Dictionary<string, decimal> PriceLocalizations  { get; set; }
public decimal PriceLocalizationsJson
{
    get => JsonSerializer.
           Serialize<Dictionary<string, decimal>>(PriceLocalizations);
    set => PriceLocalizations = JsonSerializer.
           Deserialize<Dictionary<string, decimal>>(value);
}

}


#### Dapper Localization
With Dapper, you can convert the data with a custom type handler.

csharp
using System.Text.Json;
public class NamedDictionaryTypeHandler :
SqlMapper.TypeHandler>
{
public override void SetValue(IDbDataParameter parameter,
Dictionary value)
{
parameter.Value = JsonSerializer.
Serialize>(value);
}

public override Dictionary<string, TValue> Parse(object value)
{
    var json = value as string;
    if (string.IsNullOrWhiteSpace(json))
    {
        return null;
    }
    return JsonSerializer.
           Deserialize<Dictionary<string, TValue>>(json);
}

}




The type handler must be registered at program start with `SqlMapper.AddTypeHandler(new NamedDictionaryTypeHandler<object>());`.

Use Case Driven Development with Low-Code

Jani Giannoudis — Fri, 25 Aug 2023 13:33:50 +0000

Gathering user requirements using use cases is a proven technique that Alistair Cockburn described in detail in his book Writing Effective Use Cases back in 2000. The use cases are developed during requirements engineering with the users and serve as a guide for the development of the solution. In practice, knowledge transfer from business to engineering is often difficult because of the different ways in which people work.

New technologies make it possible to build software solutions that can be created by technically skilled users themselves. The following requirements must be met:

The data model can be defined through configuration.
The available business cases with input and processing rules are described by scripts.
The business rules are checked on input (client side) and on the backend transfer (server side).
The model and its runtime behavior can be automatically tested.
The technical implementation is documented.

The following approach describes low-code solution development driven by use cases. The development requirements are

JSON - Knowledge of JSON to define the static structures.
C# - Basic knowledge of C# at the Excel function level to define the dynamic runtime behavior.

Business Case Example

To illustrate, let's take the use case of hiring an employee from HR software:

The following business rules were defined during requirements engineering:

New employees must be entered using the Employee Entry use case, after which the remaining use cases are available.
The entry date and salary must be defined when the employee joins the company.
The salary can be changed later using the Employee Salary use case.
Employees have a minimum salary of 100 and a maximum salary of 10000.
For a salary above 5000, the insurance amount can be set from 0 to 150 using the Employee Insurance use case.
The Employee Leave use case terminates the employment relationship on the leave date. After that, only the Employee Entry use case is available for re-entry.

Web Application

Cases are managed in the web application through the following pages

Cases - input of case data
Case Values - overview of the entered case values with the possibility to delete all data
Case Tests - execution of case tests

The Blazor Server application uses the open source component MudBlazor, which I recommend to C# oriented developers. To keep the application simple, all data is stored in JSON files.

The timeline is controlled by selecting the Working Day that represents the evaluation date. The available cases and case data are displayed from the time of the working day. This setting is used to simulate past and future input. In normal operation, this is the current day.

When you start the use case Employee Entry, you see a unified input mask that dynamically populates input fields based on the case definition:

When capturing the cases, the dynamic behavior is of interest:

Only the cases according to the Available expression are available.
If the start date of the entry-date field changes, this is transferred to the value (Build expression).
The input of the salary is limited to the range 100-10000.
If the salary is greater than 5000, the additional field for insurance appears.
The insurance value is limited to the range 0-150.

After executing the Employee Entry use case, the workday data is displayed. The Case Values page displays all existing time values.

The Case Tests page allows you to run custom tests:

Case Model

The business data is described by three objects:

Case - Case with fields and the script expressions for availability (Available), build (Build), and server-side validation (Validate).
Case Field - Case field with data type and basic properties such as Required, Hidden and for client-side validation the Attributes. A field can be shared by multiple cases.
Case Value - The value of a field, including the validity period of the value. Read more about Time Data.

The case model for the employee hiring use cases:

Case Configuration

The configuration of cases is done in JSON files in the WebApp\Data folder and is divided into case fields and cases.

The first step is to define the case fields.

[
  {
    "name": "EmployeeEntryDate",
    "label": "Entry date",
    "valueType": "DateTime",
    "required": true,
    "moment": true
  },
  {
    "name": "EmployeeLeaveDate",
    "label": "Leave date",
    "ValueType": "DateTime",
    "required": true,
    "moment": true
  },
  {
    "name": "EmployeeSalary",
    "label": "Salary",
    "valueType": "Decimal",
    "required": true,
    "attributes": {
      "minValue": "100",
      "maxValue": "10000"
    }
  },
  {
    "name": "EmployeeInsurance",
    "label": "Insurance",
    "valueType": "Decimal",
    "hidden": true,
    "attributes": {
      "minValue": "0",
      "maxValue": "150"
    }
  }
]

The fields for the entry date EmployeeEntryDate and the leave date EmployeeLeaveDate are instant values (Moment) and cannot be constrained in time. For client-side validation, the constraints are defined in the Attribute dictionary.

The next step is to compose the cases with the fields and the C# expressions for the runtime behavior:

[
  {
    "name": "EmployeeEntry",
    "label": "Employee Entry",
    "availableExpression": "!HasCaseValue(\"EmployeeEntryDate\") || 
        GetCaseDateTimeValue(\"EmployeeLeaveDate\") > GetCaseDateTimeValue(\"EmployeeEntryDate\")",
    "buildExpression": "SetEditValueStart(\"EmployeeEntryDate\"); 
        SetVisibility(\"EmployeeInsurance\", GetDecimalValue(\"EmployeeSalary\") >= 5000);",
    "validateExpression": "GetEditStart(\"EmployeeEntryDate\") == GetEditStart(\"EmployeeSalary\") && 
        EditValueBetween(\"EmployeeSalary\", 100, 10000) && EditValueBetween(\"EmployeeInsurance\", 0, 150)",
    "fields": [
      "EmployeeEntryDate",
      "EmployeeSalary",
      "EmployeeInsurance"
    ]
  },
  {
    "name": "EmployeeSalary",
    "label": "Employee Salary",
    "availableExpression": "HasCaseValue(\"EmployeeEntryDate\") && 
        GetCaseDateTimeValue(\"EmployeeEntryDate\") > GetCaseDateTimeValue(\"EmployeeLeaveDate\", DateTime.MinValue)",
    "buildExpression": "SetVisibility(\"EmployeeInsurance\", GetDecimalValue(\"EmployeeSalary\") >= 5000);",
    "validateExpression": "EditValueBetween(\"EmployeeSalary\", 100, 10000) &&
        EditValueBetween(\"EmployeeInsurance\", 0, 150)",
    "fields": [
      "EmployeeSalary",
      "EmployeeInsurance"
    ]
  },
  {
    "name": "EmployeeLeave",
    "label": "Employee Leave",
    "availableExpression": "HasCaseValue(\"EmployeeEntryDate\") && 
        GetCaseDateTimeValue(\"EmployeeEntryDate\") > GetCaseDateTimeValue(\"EmployeeLeaveDate\", DateTime.MinValue)",
    "buildExpression": "SetEditValueStart(\"EmployeeLeaveDate\")",
    "fields": [
      "EmployeeLeaveDate"
    ]
  }
]

Case	Expression	Description
`EmployeeEntry`	Available	No employee entry or previous exit
	Build	Synchronize entry date with the start date
	Validate	Check valid entry date and salary limits
`EmployeeSalary`	Available	Employee is employed
	Build	Show or hide the insurance value depending on the salary limit amount
	Validate	Check limits for salary and insurance
`EmployeeLeave`	Available	Employee is employed
	Build	Synchronize leaving date with the start date

Test Configuration

The configuration of the tests is also done in JSON files in the WebApp\Tests folder, divided into Available, Build, and Validate.

The following example describes the validation test for the Employee Entry use case:

[
  {
    "name": "EmployeeEntryVaildateTest",
    "caseName": "EmployeeEntry",
    "expectedValid": true,
    "caseValues": [
      {
        "field": "EmployeeEntryDate",
        "period": {
          "start": "2023-09-01T00:00:00.0Z"
        },
        "value": "\u00222023-09-01T00:00:00.0Z\u0022"
      },
      {
        "field": "EmployeeSalary",
        "period": {
          "start": "2023-09-01T00:00:00.0Z"
        },
        "value": "3500"
      }
    ]
  }
]

With caseValues all input values are simulated and a valid validation result expectedValid is expected. Other tests show how to test for changes in case fields (expectedCaseFields) and case values (expectedCaseValues).

Behind the scenes

At runtime, the Case C# expressions are embedded into a function and dynamically compiled into an assembly using the Roslyn C# compiler. Then the function that contains the expression is called (e.g. CaseAvailableFunction.Availablle()). At runtime, the function provides various methods to access stored case values as well as the current input data.

Case Classes

The cases with the functions and runtime have the following class hierarchy:

Case Functions

Function classes are embedded resources in which the expression is embedded. C# classes can be used in .NET for compilation and as an embedded resource at the same time. This requires the following manual changes to the CaseManagement.csproj project file.

<ItemGroup>
    <EmbeddedResource Include="Function\CaseFunction.cs">
        <LogicalName>Function\CaseFunction.cs</LogicalName>
    </EmbeddedResource>
    <EmbeddedResource Include="Function\CaseChangeFunction.cs">
      <LogicalName>Function\CaseChangeFunction.cs</LogicalName>
    </EmbeddedResource>
    <EmbeddedResource Include="Function\CaseAvailableFunction.cs">
        <LogicalName>Function\CaseAvailableFunction.cs</LogicalName>
    </EmbeddedResource>
    <EmbeddedResource Include="Function\CaseBuildFunction.cs">
        <LogicalName>Function\CaseBuildFunction.cs</LogicalName>
    </EmbeddedResource>
    <EmbeddedResource Include="Function\CaseValidateFunction.cs">
        <LogicalName>Function\CaseValidateFunction.cs</LogicalName>
    </EmbeddedResource>
</ItemGroup>

The base class CaseFunction contains methods that pass dynamic calls to the runtime.

public abstract class CaseFunction
{
    /// <summary>The function runtime</summary>
    protected dynamic Runtime { get; }

    protected CaseFunction(object runtime)
    {
        Runtime = runtime ?? 
              throw new ArgumentNullException(nameof(runtime));
    }

    /// <summary>Test for case value</summary>
    protected bool HasCaseValue(string caseFieldName, 
                                DateTime? evaluationDate = null) =>
        Runtime.HasCaseValue(caseFieldName, evaluationDate);

    ...
}

Case Runtimes

The request is processed in the CaseRuntime runtime class.

public abstract class CaseRuntime
{
    private readonly CaseValueService valueService = new();
    protected CaseRuntimeContext Context { get; }

    protected CaseRuntime(CaseRuntimeContext context)
    {
        Context = context ?? 
                  throw new ArgumentNullException(nameof(context));
    }

    /// <summary>Test for case value</summary>
    public bool HasCaseValue(string caseFieldName, 
                             DateTime? evaluationDate = null) =>
        valueService.GetCaseValue(caseFieldName, evaluationDate ??
                                  Context.EvaluationDate) != null;

   ...
}

Low-Code Documentation

Tools like DocFx provide the ability to display the programmable functions in HTML pages. They are used with the following commands in the docfx folder:

Static.Build.cmd - builds static HTML documentation
Static.Start.cmd - starts the static HTML documentation (requires the build command)
Server.Start.cmd - starts the DocFx application running on the local host http://localhost:5865/ (dark mode support).

The HTML help file contains a description of all low-code classes:

Extension Levels

Based on this concept, I implemented several features, some of which I will describe in future articles.

Feature	Description
No-Code Development	The dynamic composition of the function can include predefined `Actions`, such as the format of a social security number. Actions are configured from a list.
Case Relation	For more complex case compositions, the relationship between cases can be mapped in a `Case Relation`. This has a `Build` and `Validate` specification analogous to the `Case`.
List Values	With `Case Slots`, multiple values can be mapped to a field in an array. The value access is not indexed, but accessed by the slot name.
Assembly Cache	For performance critical applications, the function assembly can be cached.

Source Code

👉 The source code is available in the GitHub repository Giannoudis/UseCaseDrivenDevelopment.

REST API Visibility Control

Jani Giannoudis — Sun, 20 Aug 2023 10:31:54 +0000

REST API Visibility Control

Tools such a Swagger are widely used to document REST APIs. REST endpoints are grouped by controller and may have a name (OperationId).
The UI typically shows all REST endpoints, which is not always desirable.

Hide endpoints that cannot be controlled from the UI.
Show or hide endpoints based on application context, such as audits or experience/integration levels.
Reduce endpoints in development for startup optimization and UI reduction.

The following solution approach shows how to show or hide REST endpoints based on configuration.

👉 Hiding an endpoint does not affect its availability; REST clients can still use it without restriction.

Filter Configuration

Endpoint visibility is defined in the appsettings.json application configuration file, where visible and/or invisible filters are set. The following options are available:

Filter on visible endpoints
Filter on invisible endpoints
Combined filter of visible endpoints with a subset of invisible endpoints.

The endpoint filter is an expression in ControllerMask[.OperationMask] format and supports ? and * masks.

Examples of filter expressions:

WeatherForecast - all endpoints of the WeatherForecast controller
*Audit - all endpoints of the controller whose name ends with Audit
WeatherForecast.Get* - all endpoints of the WeatherForecast controller whose operation name begins with Get.
*.Get* - all endpoints whose operation name begins with Get.

This results in the following usage matrix:

Mode	Visible	Hidden	Example
Include	✔️	❌	`"VisibleItems": ["User.", "WeatherForecast.Get"]`
Exclude	❌	✔️	`"HiddenItems": ["User.*", "WeatherForecast.DeleteWeatherForecast"]`
Mixed	✔️	✔️	`"VisibleItems": [".Get"],` `"HiddenItems": ["User.Get*"]`

The filters are defined in the ApiConfiguration section of the configuration file. Example Include filter:

"ApiConfiguration": {
  "VisibleItems": [
    "User.*",
    "WeatherForecast.Get*"
  ]
}

Example Exclude filter:

"ApiConfiguration": {
  "HiddenItems": [
    "User.*",
    "WeatherForecast.DeleteWeatherForecast"
  ]
}

Example of an Include filter combined with an Exclude filter:

"ApiConfiguration": {
  "VisibleItems": [
    "*.Get*"
  ],
  "HiddenItems": [
    "User.Get*"
  ]
}

👉 In development mode, it is recommended that you outsource endpoint configuration to User Secrets.

Filter Convention

ASP.NET provides the ability to define the visibility of endpoints using the ActionModelConvention. The ApiVisibilityConvention implementation controls the visibility of the endpoint based on visible and invisible elements:

internal sealed class ApiVisibilityConvention : IActionModelConvention
{
    private List<string> VisibleItems { get; }
    private List<string> HiddenItems { get; }

    /// <summary>
    /// Constructor
    /// </summary>
    /// <param name="visibleItems">List of visible items name masks (wildcards: *?)</param>
    /// <param name="hiddenItems">List of hidden items name masks (wildcards: *?)</param>
    internal ApiVisibilityConvention(
        IEnumerable<string>? visibleItems = null,
        IEnumerable<string>? hiddenItems = null)
    {
        VisibleItems = visibleItems != null ? new(visibleItems) : new();
        HiddenItems = hiddenItems != null ? new(hiddenItems) : new();
    }

    public void Apply(ActionModel action)
    {
        // visible
        if (VisibleItems.Count > 0)
        {
            action.ApiExplorer.IsVisible = VisibleItems.Any(
                x => MatchItem(action.Controller.ControllerName,
                               GetOperationId(action), x));
        }

        // hidden
        if (HiddenItems.Count > 0)
        {
            if (VisibleItems.Count > 0)
            {
                // exclude from visible
                if (action.ApiExplorer.IsVisible == true)
                {
                    action.ApiExplorer.IsVisible = !HiddenItems.Any(
                        x => MatchItem(action.Controller.ControllerName, 
                                GetOperationId(action), x));
                }
            }
            else
            {
                action.ApiExplorer.IsVisible = !HiddenItems.Any(
                    x => MatchItem(action.Controller.ControllerName, 
                                GetOperationId(action), x));
            }
        }
    }

    private static string? GetOperationId(ActionModel action) =>
        (action.Attributes.FirstOrDefault(
       x => x is HttpMethodAttribute) as HttpMethodAttribute)?.Name;

    private static bool MatchItem(string controllerName,
                            string? operationId, string mask)
    {
        var controllerMask = mask;
        string? actionMask = null;

        var actionIndex = mask.IndexOf('.');
        if (actionIndex > 0)
        {
            controllerMask = mask.Substring(0, actionIndex);
            actionMask = mask.Substring(actionIndex + 1);
        }

        // controller mask only
        if (actionMask == null || string.IsNullOrWhiteSpace(operationId))
        {
            return MatchExpression(controllerName, controllerMask);
        }

        // controller and action mask
        return MatchExpression(controllerName, controllerMask) &&
               MatchExpression(operationId, actionMask);
    }

    private static bool MatchExpression(string text, string expression)
    {
        // no mask: simple string compare
        if (!expression.Contains('?') && !expression.Contains('*'))
        {
            return string.Equals(text, expression,
                    StringComparison.InvariantCultureIgnoreCase);
        }

        // regex
        var regex = new Regex(expression.Replace(".", "
                    [.]").Replace("*", ".*").Replace('?', '.'));
        return regex.IsMatch(text);
    }
}

Applying Endpoint Filters

The filters are read from the ApiConfiguration configuration at program startup and the ApiVisibilityConvention is registered when controllers are added:

1 public class Program
2 {
3    public static void Main(string[] args)
4    {
5        var builder = WebApplication.CreateBuilder(args);
6
7        // configuration
8        IConfiguration Configuration = new ConfigurationBuilder()
9            .AddJsonFile("appsettings.json", optional: true, 
                                             reloadOnChange: true)
10            .AddEnvironmentVariables()
11            .AddCommandLine(args)
12            .Build();
13        var apiConfiguration = Configuration.GetSection(
               nameof(ApiConfiguration)).Get<ApiConfiguration>();
14
15        // Add services to the container.
16        builder.Services.AddControllers(setupAction =>
17        {
18            if (apiConfiguration != null)
19            {
20                setupAction.Conventions.Add(
                      new ApiVisibilityConvention(
21                      apiConfiguration.VisibleItems,
22                      apiConfiguration.HiddenItems));
23            }
24        });
25
26        // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
27        builder.Services.AddEndpointsApiExplorer();
28        builder.Services.AddSwaggerGen();
29
30        var app = builder.Build();
31
32        // Configure the HTTP request pipeline.
33        if (app.Environment.IsDevelopment())
34        {
35            app.UseSwagger();
36            // show operation id
37            app.UseSwaggerUI(setupAction =>
38            {
39                setupAction.DisplayOperationId();
40            });
41        }
42
43        app.UseHttpsRedirection();
44
45        app.UseAuthorization();
46
47
48        app.MapControllers();
49
50        app.Run();
51    }
52 }

8-13 - load the filter configuration
16-24 - apply the visibility convention
39 - display the operation id (optional)

If no endpoint filter is active, all available endpoints are displayed in the Web UI:

Endpoints with the Include filter "VisibleItems": ["User.*", "WeatherForecast.Get*"]:

Endpoints with the Exclude filter "HiddenItems": ["User.*", "WeatherForecast.DeleteWeatherForecast"]:

Endpoints with the Exclude and Include filters "VisibleItems": ["*.Get*"], and "HiddenItems": ["User.Get*"]:

Source Code and Package

👉 GitHub Repository
👉 NuGet

Time Period Library for .NET

Jani Giannoudis — Fri, 18 Aug 2023 12:24:40 +0000

Introduction

When implementing some software for another project, I came across several requirements involving calculations with time periods. These calculations were an important part of the solution and had high demands in respect to the correctness and accuracy of the results.

The required functionality covered the following areas:

Support for individual time periods
Working with calendar periods within calendar years
Working with calendar periods deviating from the calendar year (fiscal or school periods)
Working with the accounting and broadcast calendar

The time calculations should be made available to both server components (Web Services and tasks) as well as for a rich client (WPF and Silverlight) and mobile devices.

Analyzing the situation brought me to the conclusion that neither the components of the .NET Framework (which I didn't expect) nor any other available tools would cover all the requirements. Because I already encountered similar needs in earlier projects, I decided to develop a generic library for this purpose.

From several development cycles resulted the following library Time Period, which is now available for the following .NET runtime environments:

.NET Framework from Version 3.5 or newer
.NET Core Framework
.NET Mono Framework
Xamarin
Universal Windows Platform - UWP

Time Periods

The .NET Framework already offers the extensive base classes DateTime and TimeSpan for basic time related calculations. The library Time Period extends the .NET Framework by several classes for handling periods of time. Such periods are basically characterized by a start, a duration, and an end:

Per definition, the start always occurs before the end. The start is considered undefined if it holds the minimal possible value (DateTime.MinValue). Likewise, the end is undefined if it holds the maximal possible value (DateTime.MaxValue).

The implementation of these time periods is based on the interface ITimePeriod and extended by the specializations ITimeRange, ITimeBlock and and ITimeInterval:

The interface ITimePeriod offers information and operations for time periods without defining the ways in which the crucial properties are being calculated:

Start, End, and Duration of the time period
HasStart is true if the Start time is defined
HasEnd is true if the End time is defined
IsAnytime is true if neither the Start nor the End times are defined
IsMoment is true if Start and End hold identical values
IsReadOnly is true for immutable time periods (for its usage, see below)

The relation of two time periods is described by the enumeration PeriodRelation:

Methods like IsSamePeriod, HasInside, OverlapsWith, or IntersectsWith are available for convenience to query for special, often used variants of such period relations.

Time Range

TimeRange as an implementation of ITimeRange defines the time period by its Start and End; the duration is calculated from these:

A TimeRange can be created by specifying its Start/End, Start/Duration, or Duration/End. If required, the given Start and End will be sorted chronologically.

For the modification of such a time period, various operations are available (Orange = new instance):

The following example shows the usage of TimeRange:

public void TimeRangeSample()
{
  // --- time range 1 ---
  TimeRange timeRange1 = new TimeRange(
    new DateTime( 2011, 2, 22, 14, 0, 0 ),
    new DateTime( 2011, 2, 22, 18, 0, 0 ) );
  Console.WriteLine( "TimeRange1: " + timeRange1 );
  // > TimeRange1: 22.02.2011 14:00:00 - 18:00:00 | 04:00:00

  // --- time range 2 ---
  TimeRange timeRange2 = new TimeRange(
    new DateTime( 2011, 2, 22, 15, 0, 0 ),
    new TimeSpan( 2, 0, 0 ) );
  Console.WriteLine( "TimeRange2: " + timeRange2 );
  // > TimeRange2: 22.02.2011 15:00:00 - 17:00:00 | 02:00:00

  // --- time range 3 ---
  TimeRange timeRange3 = new TimeRange(
    new DateTime( 2011, 2, 22, 16, 0, 0 ),
    new DateTime( 2011, 2, 22, 21, 0, 0 ) );
  Console.WriteLine( "TimeRange3: " + timeRange3 );
  // > TimeRange3: 22.02.2011 16:00:00 - 21:00:00 | 05:00:00

  // --- relation ---
  Console.WriteLine( "TimeRange1.GetRelation( TimeRange2 ): " +
                     timeRange1.GetRelation( timeRange2 ) );
  // > TimeRange1.GetRelation( TimeRange2 ): Enclosing
  Console.WriteLine( "TimeRange1.GetRelation( TimeRange3 ): " +
                     timeRange1.GetRelation( timeRange3 ) );
  // > TimeRange1.GetRelation( TimeRange3 ): EndInside
  Console.WriteLine( "TimeRange3.GetRelation( TimeRange2 ): " +
                     timeRange3.GetRelation( timeRange2 ) );
  // > TimeRange3.GetRelation( TimeRange2 ): StartInside

  // --- intersection ---
  Console.WriteLine( "TimeRange1.GetIntersection( TimeRange2 ): " +
                     timeRange1.GetIntersection( timeRange2 ) );
  // > TimeRange1.GetIntersection( TimeRange2 ):
  //             22.02.2011 15:00:00 - 17:00:00 | 02:00:00
  Console.WriteLine( "TimeRange1.GetIntersection( TimeRange3 ): " +
                     timeRange1.GetIntersection( timeRange3 ) );
  // > TimeRange1.GetIntersection( TimeRange3 ):
  //             22.02.2011 16:00:00 - 18:00:00 | 02:00:00
  Console.WriteLine( "TimeRange3.GetIntersection( TimeRange2 ): " +
                     timeRange3.GetIntersection( timeRange2 ) );
  // > TimeRange3.GetIntersection( TimeRange2 ):
  //             22.02.2011 16:00:00 - 17:00:00 | 01:00:00
}

The following example tests whether a reservation is within the working hours of a day:

public bool IsValidReservation( DateTime start, DateTime end )
{
  if ( !TimeCompare.IsSameDay( start, end ) )
  {
    return false;  // multiple day reservation
  }

  TimeRange workingHours =
    new TimeRange( TimeTrim.Hour( start, 8 ), 
                   TimeTrim.Hour( start, 18 ) );
  return workingHours.HasInside( new TimeRange( start, end ) );
}

Time Block

TimeBlock implements the interface ITimeBlock and defines the time period by Start and Duration; the End is being calculated:

As with TimeRange, a TimeBlock can be created with Start/End, Start/Duration, or Duration/End. As above, Start and End will be automatically sorted if necessary.

For the modification of a time block, these operations are available (Orange = new instance):

The following example shows the usage of TimeBlock:

public void TimeBlockSample()
{
  // --- time block ---
  TimeBlock timeBlock = new TimeBlock(
    new DateTime( 2011, 2, 22, 11, 0, 0 ),
    new TimeSpan( 2, 0, 0 ) );
  Console.WriteLine( "TimeBlock: " + timeBlock );
  // > TimeBlock: 22.02.2011 11:00:00 - 13:00:00 | 02:00:00

  // --- modification ---
  timeBlock.Start = new DateTime( 2011, 2, 22, 15, 0, 0 );
  Console.WriteLine( "TimeBlock.Start: " + timeBlock );
  // > TimeBlock.Start: 22.02.2011 15:00:00 - 17:00:00 | 02:00:00
  timeBlock.Move( new TimeSpan( 1, 0, 0 ) );
  Console.WriteLine( "TimeBlock.Move(1 hour): " + timeBlock );
  // > TimeBlock.Move(1 hour): 22.02.2011 16:00:00 - 18:00:00 | 02:00:00

  // --- previous/next ---
  Console.WriteLine( "TimeBlock.GetPreviousPeriod(): " +
                     timeBlock.GetPreviousPeriod() );
  // > TimeBlock.GetPreviousPeriod(): 22.02.2011 14:00:00 - 16:00:00 | 02:00:00
  Console.WriteLine( "TimeBlock.GetNextPeriod(): " + 
                     timeBlock.GetNextPeriod() );
  // > TimeBlock.GetNextPeriod(): 22.02.2011 18:00:00 - 20:00:00 | 02:00:00
  Console.WriteLine( "TimeBlock.GetNextPeriod(+1 hour): " +
                     timeBlock.GetNextPeriod( new TimeSpan( 1, 0, 0 ) ) );
  // > TimeBlock.GetNextPeriod(+1 hour): 22.02.2011 19:00:00 - 21:00:00 | 02:00:00
  Console.WriteLine( "TimeBlock.GetNextPeriod(-1 hour): " +
                     timeBlock.GetNextPeriod( new TimeSpan( -1, 0, 0 ) ) );
  // > TimeBlock.GetNextPeriod(-1 hour): 22.02.2011 17:00:00 - 19:00:00 | 02:00:00
}

Time Interval

ITimeInterval determines its period of time like ITimeRange with a Start and an End. In addition, it is possible to control the interpretation of its Start and End by the enumeration IntervalEdge:

Closed: The boundary moment of time is included in calculations. This corresponds to the behavior of ITimeRange.
Open: The boundary moment of time represents a boundary value which is excluded in regard to calculations.

The possible interval variants look as follows:

Normally, edges in interval periods have the value IntervalEdge.Closed, which leads to an intersection point with adjacent time periods. As soon as one of the adjacent points has its value set to IntervalEdge.Open, no intersection point exists:

public void TimeIntervalSample()
{
  // --- time interval 1 ---
  TimeInterval timeInterval1 = new TimeInterval(
    new DateTime( 2011, 5, 8 ),
    new DateTime( 2011, 5, 9 ) );
  Console.WriteLine( "TimeInterval1: " + timeInterval1 );
  // > TimeInterval1: \[08.05.2011 - 09.05.2011\] | 1.00:00

  // --- time interval 2 ---
  TimeInterval timeInterval2 = new TimeInterval(
    timeInterval1.End,
    timeInterval1.End.AddDays( 1 ) );
  Console.WriteLine( "TimeInterval2: " + timeInterval2 );
  // > TimeInterval2: \[09.05.2011 - 10.05.2011\] | 1.00:00

  // --- relation ---
  Console.WriteLine( "Relation: " + timeInterval1.GetRelation( 
                                               timeInterval2 ) );
  // > Relation: EndTouching
  Console.WriteLine( "Intersection: " +
                     timeInterval1.GetIntersection( timeInterval2 ) );
  // > Intersection: \[09.05.2011\]

  timeInterval1.EndEdge = IntervalEdge.Open;
  Console.WriteLine( "TimeInterval1: " + timeInterval1 );
  // > TimeInterval1: \[08.05.2011 - 09.05.2011) | 1.00:00

  timeInterval2.StartEdge = IntervalEdge.Open;
  Console.WriteLine( "TimeInterval2: " + timeInterval2 );
  // > TimeInterval2: (09.05.2011 - 10.05.2011\] | 1.00:00

  // --- relation ---
  Console.WriteLine( "Relation: " + timeInterval1.GetRelation(
                                                timeInterval2 ) );
  // > Relation: Before
  Console.WriteLine( "Intersection: " +
                     timeInterval1.GetIntersection( timeInterval2 ) );
  // > Intersection:
}

For certain scenarios, as for example the search for gaps in time periods, the exclusion of period edges can lead to undesired results. In such situations, it is possible to turn off this exclusion by setting the property IsIntervalEnabled.

Time intervals without boundaries can be created using the value TimeSpec.MinPeriodDate for Start, and TimeSpec.MaxPeriodDate for End.

Time Period Container

In everyday usage, time calculations often involve several periods which can be collected in a container and operated upon as a whole. The Time Period library offers the following containers for time periods:

All containers are based on the interface ITimePeriod, so containers themselves represent a time period. Like this, they can be used in calculations like other periods, for example, ITimeRange.

The interface ITimePeriodContainer serves as the base for all containers, and offers list functionality by deriving from IList<ITimePeriod>.

Time Period Collection

A ITimePeriodCollection can hold arbitrary elements of type ITimePeriod and interprets the earliest start of all its elements as the start of the collection time period. Correspondingly, the latest end of all its elements serves as the end of the collection period:

The time period collection offers the following operations:

The following example shows the usage of the class TimePeriodCollection, which implements the interface ITimePeriodCollection:

public void TimePeriodCollectionSample()
{
  TimePeriodCollection timePeriods = new TimePeriodCollection();

  DateTime testDay = new DateTime( 2010, 7, 23 );

  // --- items ---
  timePeriods.Add( new TimeRange( TimeTrim.Hour( testDay, 8 ),
                   TimeTrim.Hour( testDay, 11 ) ) );
  timePeriods.Add( new TimeBlock( TimeTrim.Hour( testDay, 10 ), 
                   Duration.Hours( 3 ) ) );
  timePeriods.Add( new TimeRange( TimeTrim.Hour( testDay, 16, 15 ),
                   TimeTrim.Hour( testDay, 18, 45 ) ) );
  timePeriods.Add( new TimeRange( TimeTrim.Hour( testDay, 14 ),
                   TimeTrim.Hour( testDay, 15, 30 ) ) );
  Console.WriteLine( "TimePeriodCollection: " + timePeriods );
  // > TimePeriodCollection: Count = 4; 23.07.2010 08:00:00 - 
                                                18:45:00 | 0.10:45
  Console.WriteLine( "TimePeriodCollection.Items" );
  foreach ( ITimePeriod timePeriod in timePeriods )
  {
    Console.WriteLine( "Item: " + timePeriod );
  }
  // > Item: 23.07.2010 08:00:00 - 11:00:00 | 03:00:00
  // > Item: 23.07.2010 10:00:00 - 13:00:00 | 03:00:00
  // > Item: 23.07.2010 16:15:00 - 18:45:00 | 02:30:00
  // > Item: 23.07.2010 14:00:00 - 15:30:00 | 01:30:00

  // --- intersection by moment ---
  DateTime intersectionMoment = new DateTime( 2010, 7, 23, 10, 30, 0 );
  ITimePeriodCollection momentIntersections =
     timePeriods.IntersectionPeriods( intersectionMoment );
  Console.WriteLine( "TimePeriodCollection.IntesectionPeriods of " +
                     intersectionMoment );
  // > TimePeriodCollection.IntesectionPeriods of 23.07.2010 10:30:00
  foreach ( ITimePeriod momentIntersection in momentIntersections )
  {
    Console.WriteLine( "Intersection: " + momentIntersection );
  }
  // > Intersection: 23.07.2010 08:00:00 - 11:00:00 | 03:00:00
  // > Intersection: 23.07.2010 10:00:00 - 13:00:00 | 03:00:00

  // --- intersection by period ---
  TimeRange intersectionPeriod =
    new TimeRange( TimeTrim.Hour( testDay, 9 ),
                   TimeTrim.Hour( testDay, 14, 30 ) );
  ITimePeriodCollection periodIntersections =
    timePeriods.IntersectionPeriods( intersectionPeriod );
  Console.WriteLine( "TimePeriodCollection.IntesectionPeriods of " +
                     intersectionPeriod );
  // > TimePeriodCollection.IntesectionPeriods
  //      of 23.07.2010 09:00:00 - 14:30:00 | 0.05:30
  foreach ( ITimePeriod periodIntersection in periodIntersections )
  {
    Console.WriteLine( "Intersection: " + periodIntersection );
  }
  // > Intersection: 23.07.2010 08:00:00 - 11:00:00 | 03:00:00
  // > Intersection: 23.07.2010 10:00:00 - 13:00:00 | 03:00:00
  // > Intersection: 23.07.2010 14:00:00 - 15:30:00 | 01:30:00
}

Time Period Chain

ITimePeriodChain connects several time periods of type ITimePeriod in a chain and ensures that no gaps exist between successive periods:

Because ITimePeriodChain might change the position of elements, no read-only time periods can be added. Attempting this leads to a NotSupportedException. ITimePeriodChain offers the following functionality:

The following example shows the usage of class TimePeriodChain, which implements the interface ITimePeriodChain:

public void TimePeriodChainSample()
{
  TimePeriodChain timePeriods = new TimePeriodChain();

  DateTime now = ClockProxy.Clock.Now;
  DateTime testDay = new DateTime( 2010, 7, 23 );

  // --- add ---
  timePeriods.Add( new TimeBlock(
                   TimeTrim.Hour( testDay, 8 ), Duration.Hours( 2 ) ) );
  timePeriods.Add( new TimeBlock( now, Duration.Hours( 1, 30 ) ) );
  timePeriods.Add( new TimeBlock( now, Duration.Hour ) );
  Console.WriteLine( "TimePeriodChain.Add(): " + timePeriods );
  // > TimePeriodChain.Add(): Count = 3; 23.07.2010 08:00:00 - 
                                               12:30:00 | 0.04:30
  foreach ( ITimePeriod timePeriod in timePeriods )
  {
    Console.WriteLine( "Item: " + timePeriod );
  }
  // > Item: 23.07.2010 08:00:00 - 10:00:00 | 02:00:00
  // > Item: 23.07.2010 10:00:00 - 11:30:00 | 01:30:00
  // > Item: 23.07.2010 11:30:00 - 12:30:00 | 01:00:00

  // --- insert ---
  timePeriods.Insert( 2, new TimeBlock( now, Duration.Minutes( 45 ) ) );
  Console.WriteLine( "TimePeriodChain.Insert(): " + timePeriods );
  // > TimePeriodChain.Insert(): Count = 4; 23.07.2010 08:00:00 -
                                                13:15:00 | 0.05:15
  foreach ( ITimePeriod timePeriod in timePeriods )
  {
    Console.WriteLine( "Item: " + timePeriod );
  }
  // > Item: 23.07.2010 08:00:00 - 10:00:00 | 02:00:00
  // > Item: 23.07.2010 10:00:00 - 11:30:00 | 01:30:00
  // > Item: 23.07.2010 11:30:00 - 12:15:00 | 00:45:00
  // > Item: 23.07.2010 12:15:00 - 13:15:00 | 01:00:00
}

Calendar Time Periods

Calculations with calendar periods must consider the peculiarity that the end of a time period doesn't equal the start of the following period. The following example shows the corresponding values for the hours of day between 13h and 15h:

13:00:00.0000000 - 13:59:59.9999999
14:00:00.0000000 - 14:59:59.9999999

The end lies a moment before the next start, the difference between the two is at least 1 Tick = 100 nanoseconds. This is an important aspect and may not be neglected in calculations involving time periods.

The Time Period library offers the interface ITimePeriodMapper, which can convert moments of a time period in both directions. Applied to the scenario above, this would be handled as follows:

public void TimePeriodMapperSample()
{
  TimeCalendar timeCalendar = new TimeCalendar();
  CultureInfo ci = CultureInfo.InvariantCulture;

  DateTime start = new DateTime( 2011, 3, 1, 13, 0, 0 );
  DateTime end = new DateTime( 2011, 3, 1, 14, 0, 0 );

  Console.WriteLine( "Original start: {0}",
                     start.ToString( "HH:mm:ss.fffffff", ci ) );
  // > Original start: 13:00:00.0000000
  Console.WriteLine( "Original end: {0}",
                     end.ToString( "HH:mm:ss.fffffff", ci ) );
  // > Original end: 14:00:00.0000000

  Console.WriteLine( "Mapping offset start: {0}", 
                     timeCalendar.StartOffset );
  // > Mapping offset start: 00:00:00
  Console.WriteLine( "Mapping offset end: {0}", 
                     timeCalendar.EndOffset );
  // > Mapping offset end: -00:00:00.0000001

  Console.WriteLine( "Mapped start: {0}",
    timeCalendar.MapStart( start ).ToString( "HH:mm:ss.fffffff", ci ) );
  // > Mapped start: 13:00:00.0000000
  Console.WriteLine( "Mapped end: {0}",
    timeCalendar.MapEnd( end ).ToString( "HH:mm:ss.fffffff", ci ) );
  // > Mapped end: 13:59:59.9999999
}

Time Calendar

The task of interpretation of time periods of calendar elements is combined in the interface ITimeCalendar:

ITimeCalendar covers the following areas:

Assignment to a CultureInfo (default = CultureInfo of the current thread)
Mapping of period boundaries (ITimePeriodMapper)
Base month of the year (default = January)
Definition of how to interpret calendar weeks
Definition for accounting calendar
Naming of periods like, for example, the name of the year (fiscal year, school year, ...)
Various calendar related calculations

Deriving from ITimePeriodMapper, the mapping of time period boundaries happens with the properties StartOffset (default = 0) and EndOffset (default = -1 Tick).

The following example shows a specialization of a time calendar for a fiscal year:

public class FiscalTimeCalendar : TimeCalendar
{
  public FiscalTimeCalendar(): 
  base(
      new TimeCalendarConfig
      {
        YearBaseMonth = YearMonth.October,  //  October year base month
        YearWeekType = YearWeekType.Iso8601, // ISO 8601 week numbering
        YearType = YearType.FiscalYear // treat years as fiscal years
      } )
  {
  }
}

This time calendar can now be used as follows:

public void FiscalYearSample()
{
  // use fiscal periods
  FiscalTimeCalendar calendar = new FiscalTimeCalendar();

  DateTime moment1 = new DateTime( 2006, 9, 30 );
  Console.WriteLine( "Fiscal Year of {0}: {1}", 
                     moment1.ToShortDateString(),
                     new Year( moment1, calendar ).YearName );
  // > Fiscal Year of 30.09.2006: FY2005
  Console.WriteLine( "Fiscal Quarter of {0}: {1}", 
                     moment1.ToShortDateString(),
                     new Quarter( moment1, calendar )
                         .QuarterOfYearName );
  // > Fiscal Quarter of 30.09.2006: FQ4 2005

  DateTime moment2 = new DateTime( 2006, 10, 1 );
  Console.WriteLine( "Fiscal Year of {0}: {1}", 
                     moment2.ToShortDateString(),
                     new Year( moment2, calendar ).YearName );
  // > Fiscal Year of 01.10.2006: FY2006
  Console.WriteLine( "Fiscal Quarter of {0}: {1}", 
                     moment1.ToShortDateString(),
                     new Quarter( moment2, calendar )
                         .QuarterOfYearName );
  // > Fiscal Quarter of 30.09.2006: FQ1 2006
}

A more thorough description of the classes Year and Quarter follows below.

Calendar Elements

For the most commonly used calendar elements, specialized classes are available:

Time period	Single period	Multiple periods	Refers to year's base month
Year	`Year`	`Years`	Yes
Broadcast year	`BroadcastYear`	-	No
Half year	`Halfyear`	`Halfyears`	Yes
Quarter	`Quarter`	`Quarters`	Yes
Month	`Month`	`Months`	No
Broadcast month	`BroadcastMonth`	-	No
Week	`Week`	`Weeks`	No
Broadcast week	`BroadcastWeek`	-	No
Day	`Day`	`Days`	No
Hour	`Hour`	`Hours`	No
Minute	`Minute`	`Minutes`	No

Instantiating elements with multiple periods can happen with a specified number of periods.

The following diagram shows the calendar elements for quarters and months, other elements are analogous:

All calendar elements derive from the base class CalendarTimeRange which itself derives from TimeRange. CalendarTimeRange contains the time calendar ITimeCalendar and thus ensures that the values of the time period cannot be changed after creation (IsReadOnly=true).

Because by inheritance through the base class TimePeriod, the calendar elements implement the interface ITimePeriod, they can all be used for calculations with other time periods.

The following example shows various calendar elements:

public void CalendarYearTimePeriodsSample()
{
  DateTime moment = new DateTime( 2011, 8, 15 );
  Console.WriteLine( "Calendar Periods of {0}:", 
                     moment.ToShortDateString() );
  // > Calendar Periods of 15.08.2011:
  Console.WriteLine( "Year     : {0}", new Year( moment ) );
  Console.WriteLine( "Halfyear : {0}", new Halfyear( moment ) );
  Console.WriteLine( "Quarter  : {0}", new Quarter( moment ) );
  Console.WriteLine( "Month    : {0}", new Month( moment ) );
  Console.WriteLine( "Week     : {0}", new Week( moment ) );
  Console.WriteLine( "Day      : {0}", new Day( moment ) );
  Console.WriteLine( "Hour     : {0}", new Hour( moment ) );
  // > Year     : 2011; 01.01.2011 - 31.12.2011 | 364.23:59
  // > Halfyear : HY2 2011; 01.07.2011 - 31.12.2011 | 183.23:59
  // > Quarter  : Q3 2011; 01.07.2011 - 30.09.2011 | 91.23:59
  // > Month    : August 2011; 01.08.2011 - 31.08.2011 | 30.23:59
  // > Week     : w/c 33 2011; 15.08.2011 - 21.08.2011 | 6.23:59
  // > Day      : Montag; 15.08.2011 - 15.08.2011 | 0.23:59
  // > Hour     : 15.08.2011; 00:00 - 00:59 | 0.00:59
}

Some specific calendar elements offer methods to access the time periods of their sub-elements. The following example shows the quarters of a calendar year:

public void YearQuartersSample()
{
  Year year = new Year( 2012 );
  ITimePeriodCollection quarters = year.GetQuarters();
  Console.WriteLine( "Quarters of Year: {0}", year );
  // > Quarters of Year: 2012; 01.01.2012 - 31.12.2012 | 365.23:59
  foreach ( Quarter quarter in quarters )
  {
    Console.WriteLine( "Quarter: {0}", quarter );
  }
  // > Quarter: Q1 2012; 01.01.2012 - 31.03.2012 | 90.23:59
  // > Quarter: Q2 2012; 01.04.2012 - 30.06.2012 | 90.23:59
  // > Quarter: Q3 2012; 01.07.2012 - 30.09.2012 | 91.23:59
  // > Quarter: Q4 2012; 01.10.2012 - 31.12.2012 | 91.23:59
}

Year and Year Periods

A peculiarity of the calendar elements is their support for calendar periods which deviate from (normal) calendar years:

The beginning of the year can be set through the property ITimeCalendar.YearBaseMonth and will be considered by the calendar elements Year, Half Year, and Quarter. Valid values for the start of a year can be an arbitrary month. The calendar year thus simply represents the special case where YearBaseMonth = YearMonth.January.

The following properties govern the interpretation of the boundaries between years:

MultipleCalendarYears holds true if a period spans over multiple calendar years
IsCalendarYear/Halfyear/Quarter holds true if a period corresponds the one of the calendar year

Fiscal years which start in July or later conventionally use the year number of the following calendar year. The calendar property FiscalYearBaseMonth offers the possibility to define the month, after which the fiscal year will be assigned the following calendar year.

The following example shows the calendar elements of a fiscal year:

public void FiscalYearTimePeriodsSample()
{
  DateTime moment = new DateTime( 2011, 8, 15 );
  FiscalTimeCalendar fiscalCalendar = new FiscalTimeCalendar();
  Console.WriteLine( "Fiscal Year Periods of {0}:", 
                     moment.ToShortDateString() );
  // > Fiscal Year Periods of 15.08.2011:
  Console.WriteLine( "Year     : {0}", 
                     new Year( moment, fiscalCalendar ) );
  Console.WriteLine( "Halfyear : {0}", 
                     new Halfyear( moment, fiscalCalendar ) );
  Console.WriteLine( "Quarter  : {0}",
                     new Quarter( moment, fiscalCalendar ) );
  // > Year     : FY2010; 01.10.2010 - 30.09.2011 | 364.23:59
  // > Halfyear : FHY2 2010; 01.04.2011 - 30.09.2011 | 182.23:59
  // > Quarter  : FQ4 2010; 01.07.2011 - 30.09.2011 | 91.23:59
}

Moving the beginning of the year influences the outcome of all contained elements and their operations:

public void YearStartSample()
{
  TimeCalendar calendar = new TimeCalendar(
    new TimeCalendarConfig { YearBaseMonth = YearMonth.February } );

  Years years = new Years( 2012, 2, calendar ); // 2012-2013
  Console.WriteLine( "Quarters of Years (February): {0}", years );
  // > Quarters of Years (February): 2012 - 2014; 01.02.2012 - 
                                          31.01.2014 | 730.23:59

  foreach ( Year year in years.GetYears() )
  {
    foreach ( Quarter quarter in year.GetQuarters() )
    {
      Console.WriteLine( "Quarter: {0}", quarter );
    }
  }
  // > Quarter: Q1 2012; 01.02.2012 - 30.04.2012 | 89.23:59
  // > Quarter: Q2 2012; 01.05.2012 - 31.07.2012 | 91.23:59
  // > Quarter: Q3 2012; 01.08.2012 - 31.10.2012 | 91.23:59
  // > Quarter: Q4 2012; 01.11.2012 - 31.01.2013 | 91.23:59
  // > Quarter: Q1 2013; 01.02.2013 - 30.04.2013 | 88.23:59
  // > Quarter: Q2 2013; 01.05.2013 - 31.07.2013 | 91.23:59
  // > Quarter: Q3 2013; 01.08.2013 - 31.10.2013 | 91.23:59
  // > Quarter: Q4 2013; 01.11.2013 - 31.01.2014 | 91.23:59
}

Following are some illustrative usages of often useful utility functions:

public bool IntersectsYear( DateTime start, DateTime end, int year )
{
  return new Year( year ).IntersectsWith( new TimeRange( start, end ) );
}

public void GetDaysOfPastQuarter( DateTime moment,
       out DateTime firstDay, out DateTime lastDay )
{
  TimeCalendar calendar = new TimeCalendar(
    new TimeCalendarConfig { YearBaseMonth = YearMonth.October } );
  Quarter quarter = new Quarter( moment, calendar );
  Quarter pastQuarter = quarter.GetPreviousQuarter();

  firstDay = pastQuarter.FirstDayStart;
  lastDay = pastQuarter.LastDayStart;
}

public DateTime GetFirstDayOfWeek( DateTime moment )
{
  return new Week( moment ).FirstDayStart;
}

public bool IsInCurrentWeek( DateTime test )
{
  return new Week().HasInside( test );
}

Weeks

Common practice numbers the weeks of a year from 1 to 52/53. The .NET Framework offers in Calendar.GetWeekOfYear a method to get at this number of the week for a given moment in time. Unfortunately, this deviates from the definition given in ISO 8601, which can lead to wrong interpretations and other misbehavior.

The Time Period library contains the enumeration YearWeekType, which controls the calculation of calendar week numbers according to ISO 8601. YearWeekType is supported by ITimeCalendar and thus defines the different ways of calculation:

public void CalendarWeekSample()
{
  DateTime testDate = new DateTime( 2007, 12, 31 );

  // .NET calendar week
  TimeCalendar calendar = new TimeCalendar();
  Console.WriteLine( "Calendar Week of {0}: {1}", 
                     testDate.ToShortDateString(),
                     new Week( testDate, calendar ).WeekOfYear );
  // > Calendar Week of 31.12.2007: 53

  // ISO 8601 calendar week
  TimeCalendar calendarIso8601 = new TimeCalendar(
    new TimeCalendarConfig { YearWeekType = YearWeekType.Iso8601 } );
  Console.WriteLine( "ISO 8601 Week of {0}: {1}", 
                     testDate.ToShortDateString(),
                     new Week( testDate, calendarIso8601 ).WeekOfYear );
  // > ISO 8601 Week of 31.12.2007: 1
}

Accounting Calendar

To simplify planning, accounting related industries often structure years into quarters which are composed of months with either four or five weeks (4-4-5 calendar). Such a year is usually aligned to

the last week day of a month (FiscalYearAlignment.LastDay)
a week day close to the end of the month (FiscalYearAlignment.NearestDay)

Arrangement of the weeks occurs according to the following grouping criteria:

4-4-5 weeks (FiscalQuarterGrouping.FourFourFiveWeeks)
4-5-4 weeks (FiscalQuarterGrouping.FourFiveFourWeeks)
5-4-4 weeks (FiscalQuarterGrouping.FiveFourFourWeeks)

Control of this behavior is located in ITimeCalendar and only applies to fiscal years (YearType.FiscalYear). The calendar property FiscalFirstDayOfYear determines the week day on which a year begins.

The following example shows a fiscal year which ends on the last Saturday of August:

public void FiscalYearLastDay()
{
  ITimeCalendar calendar = new TimeCalendar( new TimeCalendarConfig
  {
    YearType = YearType.FiscalYear,
    YearBaseMonth = YearMonth.September,
    FiscalFirstDayOfYear = DayOfWeek.Sunday,
    FiscalYearAlignment = FiscalYearAlignment.LastDay,
    FiscalQuarterGrouping = FiscalQuarterGrouping.FourFourFiveWeeks
  } );

  Years years = new Years( 2005, 14, calendar );
  foreach ( Year year in years.GetYears() )
  {
    Console.WriteLine( "Fiscal year {0}: {1} - {2}", year.YearValue,
      year.Start.ToString( "yyyy-MM-dd" ), 
      year.End.ToString( "yyyy-MM-dd" ) );
  }
}

The following fiscal year ends on that Saturday which is closer to the end of August:

public void FiscalYearNearestDay()
{
  ITimeCalendar calendar = new TimeCalendar( new TimeCalendarConfig
  {
    YearType = YearType.FiscalYear,
    YearBaseMonth = YearMonth.September,
    FiscalFirstDayOfYear = DayOfWeek.Sunday,
    FiscalYearAlignment = FiscalYearAlignment.NearestDay,
    FiscalQuarterGrouping = FiscalQuarterGrouping.FourFourFiveWeeks
  } );

  Years years = new Years( 2005, 14, calendar );
  foreach ( Year year in years.GetYears() )
  {
    Console.WriteLine( "Fiscal year {0}: {1} - {2}", year.YearValue,
      year.Start.ToString( "yyyy-MM-dd" ), 
      year.End.ToString( "yyyy-MM-dd" ) );
  }
}

Broadcast Calendar

The Broadcast Calendar is supported by the classes BroadcastYear, BroadcastMonth and BroadcastWeek:

public void BroadcastCalendar()
{
  BroadcastYear year = new BroadcastYear( 2013 );
  Console.WriteLine( "Broadcast year: " + year );
  // > Broadcast year: 2013; 31.12.2012 - 29.12.2013 | 363.23:59
  foreach ( BroadcastMonth month in year.GetMonths() )
  {
    Console.WriteLine( " Broadcast month: " + month );
    foreach ( BroadcastWeek week in month.GetWeeks() )
    {
      Console.WriteLine( " Broadcast week: " + week );
    }
   }
}

Time Period Calculation Tools

Time Line

The class TimeLine is at the heart of calculations regarding time gaps and overlaps. It analyzes the time periods of a Collection by ordering them according to occurrence of the respective moments in time. Each moment on the time line is represented as an ITimeLineMoment and contains the information about which time periods start and end at a specific moment. This representation allows for keeping track of a running balance by addition and subtraction while processing a time line.

The moments of the time axis are stored in the ITimeLineMomentCollection which allows efficient access for iteration and by index based on moments of time.

Difference between Two Points of Time

The TimeSpan structure of the .NET Framework just offers the time range values for days, hours, minutes, seconds and milliseconds. From a user perspective, it is often desirable to also represent the months and years of a time range:

Last visit 1 year, 4 months and 12 days ago
Current age: 28 years

The Time Period library includes the class DateDiff, which calculates the difference in time between two date values and also offers access to the elapsed time range. This properly considers calendar periods to account for varying month durations:

public void DateDiffSample()
{
  DateTime date1 = new DateTime( 2009, 11, 8, 7, 13, 59 );
  Console.WriteLine( "Date1: {0}", date1 );
  // > Date1: 08.11.2009 07:13:59
  DateTime date2 = new DateTime( 2011, 3, 20, 19, 55, 28 );
  Console.WriteLine( "Date2: {0}", date2 );
  // > Date2: 20.03.2011 19:55:28

  DateDiff dateDiff = new DateDiff( date1, date2 );

  // differences
  Console.WriteLine( "DateDiff.Years: {0}", dateDiff.Years );
  // > DateDiff.Years: 1
  Console.WriteLine( "DateDiff.Quarters: {0}", dateDiff.Quarters );
  // > DateDiff.Quarters: 5
  Console.WriteLine( "DateDiff.Months: {0}", dateDiff.Months );
  // > DateDiff.Months: 16
  Console.WriteLine( "DateDiff.Weeks: {0}", dateDiff.Weeks );
  // > DateDiff.Weeks: 70
  Console.WriteLine( "DateDiff.Days: {0}", dateDiff.Days );
  // > DateDiff.Days: 497
  Console.WriteLine( "DateDiff.Weekdays: {0}", dateDiff.Weekdays );
  // > DateDiff.Weekdays: 71
  Console.WriteLine( "DateDiff.Hours: {0}", dateDiff.Hours );
  // > DateDiff.Hours: 11940
  Console.WriteLine( "DateDiff.Minutes: {0}", dateDiff.Minutes );
  // > DateDiff.Minutes: 716441
  Console.WriteLine( "DateDiff.Seconds: {0}", dateDiff.Seconds );
  // > DateDiff.Seconds: 42986489

  // elapsed
  Console.WriteLine( "DateDiff.ElapsedYears: {0}",
                     dateDiff.ElapsedYears );
  // > DateDiff.ElapsedYears: 1
  Console.WriteLine( "DateDiff.ElapsedMonths: {0}", 
                     dateDiff.ElapsedMonths );
  // > DateDiff.ElapsedMonths: 4
  Console.WriteLine( "DateDiff.ElapsedDays: {0}", 
                     dateDiff.ElapsedDays );
  // > DateDiff.ElapsedDays: 12
  Console.WriteLine( "DateDiff.ElapsedHours: {0}", 
                     dateDiff.ElapsedHours );
  // > DateDiff.ElapsedHours: 12
  Console.WriteLine( "DateDiff.ElapsedMinutes: {0}", 
                     dateDiff.ElapsedMinutes );
  // > DateDiff.ElapsedMinutes: 41
  Console.WriteLine( "DateDiff.ElapsedSeconds: {0}", 
                     dateDiff.ElapsedSeconds );
  // > DateDiff.ElapsedSeconds: 29

  // description
  Console.WriteLine( "DateDiff.GetDescription(1): {0}", 
                     dateDiff.GetDescription( 1 ) );
  // > DateDiff.GetDescription(1): 1 Year
  Console.WriteLine( "DateDiff.GetDescription(2): {0}", 
                     dateDiff.GetDescription( 2 ) );
  // > DateDiff.GetDescription(2): 1 Year 4 Months
  Console.WriteLine( "DateDiff.GetDescription(3): {0}", 
                     dateDiff.GetDescription( 3 ) );
  // > DateDiff.GetDescription(3): 1 Year 4 Months 12 Days
  Console.WriteLine( "DateDiff.GetDescription(4): {0}", 
                     dateDiff.GetDescription( 4 ) );
  // > DateDiff.GetDescription(4): 1 Year 4 Months 12 Days 12 Hours
  Console.WriteLine( "DateDiff.GetDescription(5): {0}", 
                     dateDiff.GetDescription( 5 ) );
  // > DateDiff.GetDescription(5): 1 Year 4 Months 12 Days 12 Hours 41 Mins
  Console.WriteLine( "DateDiff.GetDescription(6): {0}", 
                     dateDiff.GetDescription( 6 ) );
  // > DateDiff.GetDescription(6): 1 Year 4 Months 12 Days 12 Hours 41 Mins 29 Secs
}

The method DateDiff.GetDescription can format the time duration with variable level of detail.

Time Gap Calculation

A TimeGapCalculator calculates the gaps between time periods in a collection:

Interpretation of the moments of time can be subject to the application of a ITimePeriodMapper.

The following example shows how to find the largest possible gap between existing bookings while considering weekends as unavailable:

public void TimeGapCalculatorSample()
{
  // simulation of some reservations
  TimePeriodCollection reservations = new TimePeriodCollection();
  reservations.Add( new Days( 2011, 3, 7, 2 ) );
  reservations.Add( new Days( 2011, 3, 16, 2 ) );

  // the overall search range
  CalendarTimeRange searchLimits = new CalendarTimeRange(
      new DateTime( 2011, 3, 4 ), new DateTime( 2011, 3, 21 ) );

  // search the largest free time block
  ICalendarTimeRange largestFreeTimeBlock =
      FindLargestFreeTimeBlock( reservations, searchLimits );
  Console.WriteLine( "Largest free time: " + largestFreeTimeBlock );
  // > Largest free time: 09.03.2011 00:00:00 - 11.03.2011 23:59:59 | 2.23:59
}

public ICalendarTimeRange FindLargestFreeTimeBlock(
       IEnumerable<ITimePeriod> reservations,
       ITimePeriod searchLimits = null, bool excludeWeekends = true )
{
  TimePeriodCollection bookedPeriods = 
                         new TimePeriodCollection( reservations );

  if ( searchLimits == null )
  {
    searchLimits = bookedPeriods; // use boundary of reservations
  }

  if ( excludeWeekends )
  {
    Week currentWeek = new Week( searchLimits.Start );
    Week lastWeek = new Week( searchLimits.End );
    do
    {
      ITimePeriodCollection days = currentWeek.GetDays();
      foreach ( Day day in days )
      {
        if ( !searchLimits.HasInside( day ) )
        {
          continue; // outside of the search scope
        }
        if ( day.DayOfWeek == DayOfWeek.Saturday ||
             day.DayOfWeek == DayOfWeek.Sunday )
        {
          bookedPeriods.Add( day ); // // exclude weekend day
        }
      }
      currentWeek = currentWeek.GetNextWeek();
    } while ( currentWeek.Start < lastWeek.Start );
  }

  // calculate the gaps using the time calendar as period mapper
  TimeGapCalculator<TimeRange> gapCalculator =
    new TimeGapCalculator<TimeRange>( new TimeCalendar() );
  ITimePeriodCollection freeTimes =
    gapCalculator.GetGaps( bookedPeriods, searchLimits );
  if ( freeTimes.Count == 0 )
  {
    return null;
  }

  freeTimes.SortByDuration(); // move the largest gap to the start
  return new CalendarTimeRange( freeTimes\[ 0 \] );
}

Consolidation of Time Periods

In some situations, it is reasonable to have a consolidated view on overlapping or adjacent time periods - e.g., the contrary of finding gaps. The class TimePeriodCombiner offers this possibility to consolidate such time periods:

The following example shows the combination of time periods according to the illustration:

public void TimePeriodCombinerSample()
{
  TimePeriodCollection periods = new TimePeriodCollection();

  periods.Add( new TimeRange( new DateTime( 2011, 3, 01 ),
               new DateTime( 2011, 3, 10 ) ) );
  periods.Add( new TimeRange( new DateTime( 2011, 3, 04 ),
               new DateTime( 2011, 3, 08 ) ) );

  periods.Add( new TimeRange( new DateTime( 2011, 3, 15 ),
               new DateTime( 2011, 3, 18 ) ) );
  periods.Add( new TimeRange( new DateTime( 2011, 3, 18 ),
               new DateTime( 2011, 3, 22 ) ) );
  periods.Add( new TimeRange( new DateTime( 2011, 3, 20 ),
               new DateTime( 2011, 3, 24 ) ) );

  periods.Add( new TimeRange( new DateTime( 2011, 3, 26 ),
               new DateTime( 2011, 3, 30 ) ) );

  TimePeriodCombiner<TimeRange> periodCombiner =
                            new TimePeriodCombiner<TimeRange>();
  ITimePeriodCollection combinedPeriods = 
                       periodCombiner.CombinePeriods( periods );

  foreach ( ITimePeriod combinedPeriod in combinedPeriods )
  {
    Console.WriteLine( "Combined Period: " + combinedPeriod );
  }
  // > Combined Period: 01.03.2011 - 10.03.2011 | 9.00:00
  // > Combined Period: 15.03.2011 - 24.03.2011 | 9.00:00
  // > Combined Period: 26.03.2011 - 30.03.2011 | 4.00:00
}

Intersections of Time Periods

If time periods should be checked for intersections (e.g., duplicate bookings), the class TimePeriodIntersector comes to the rescue:

By default, the intersection periods are combined into one. To maintain all intersection periods, the parameter combinePeriods of the method IntersectPeriods can be set to false.

The following example shows the usage of TimePeriodIntersector:

// ----------------------------------------------------------------------
public void TimePeriodIntersectorSample()
{
  TimePeriodCollection periods = new TimePeriodCollection();

  periods.Add( new TimeRange( new DateTime( 2011, 3, 01 ),
               new DateTime( 2011, 3, 10 ) ) );
  periods.Add( new TimeRange( new DateTime( 2011, 3, 05 ), 
               new DateTime( 2011, 3, 15 ) ) );
  periods.Add( new TimeRange( new DateTime( 2011, 3, 12 ), 
               new DateTime( 2011, 3, 18 ) ) );

  periods.Add( new TimeRange( new DateTime( 2011, 3, 20 ), 
               new DateTime( 2011, 3, 24 ) ) );
  periods.Add( new TimeRange( new DateTime( 2011, 3, 22 ),
               new DateTime( 2011, 3, 28 ) ) );
  periods.Add( new TimeRange( new DateTime( 2011, 3, 24 ),
               new DateTime( 2011, 3, 26 ) ) );

  TimePeriodIntersector<TimeRange> periodIntersector =
                    new TimePeriodIntersector<TimeRange>();
  ITimePeriodCollection intersectedPeriods = 
                    periodIntersector.IntersectPeriods( periods );

  foreach ( ITimePeriod intersectedPeriod in intersectedPeriods )
  {
    Console.WriteLine( "Intersected Period: " + intersectedPeriod );
  }
  // > Intersected Period: 05.03.2011 - 10.03.2011 | 5.00:00
  // > Intersected Period: 12.03.2011 - 15.03.2011 | 3.00:00
  // > Intersected Period: 22.03.2011 - 26.03.2011 | 4.00:00
}

Subtraction of Time Periods

Using the class TimePeriodSubtractor you can subtract time periods (subtrahend) from other time periods (minuend):

The result contains the differences between the two time period collections:

public void TimePeriodSubtractorSample()
{
  DateTime moment = new DateTime( 2012, 1, 29 );
  TimePeriodCollection sourcePeriods = new TimePeriodCollection
    {
        new TimeRange( moment.AddHours( 2 ), moment.AddDays( 1 ) )
    };

  TimePeriodCollection subtractingPeriods = new TimePeriodCollection
    {
        new TimeRange( moment.AddHours( 6 ), moment.AddHours( 10 ) ),
        new TimeRange( moment.AddHours( 12 ), moment.AddHours( 16 ) )
    };

  TimePeriodSubtractor<timerange> subtractor =
                            new TimePeriodSubtractor<timerange>();
  ITimePeriodCollection subtractedPeriods =
    subtractor.SubtractPeriods( sourcePeriods, subtractingPeriods );
  foreach ( TimeRange subtractedPeriod in subtractedPeriods )
  {
    Console.WriteLine( "Subtracted Period: {0}", subtractedPeriod );
  }
  // > Subtracted Period : 29.01.2012 02:00:00 - 06:00:00 | 0.04:00
  // > Subtracted Period : 29.01.2012 10:00:00 - 12:00:00 | 0.02:00
  // > Subtracted Period : 29.01.2012 16:00:00 - 30.01.2012 00:00:00 | 0.08:00
}

Addition and Subtraction of Dates

Often, the problem arises to add a certain time period to a given date and from that derive the target point of time. What at first sounds easy is often complicated by several factors:

only business hours should be considered
weekends, holidays, service and maintenance periods should be excluded

As soon as there exist such requirements, common date arithmetic will invariably fail. In such cases, the class DateAdd might come to the rescue:

Although the name of the class might suggest otherwise, it is possible to do addition as well as subtraction. A peculiarity of DateAdd is its capability of specifying periods to include with DateAdd.IncludePeriods as well as exclude certain periods with DateAdd.ExcludePeriods. It is also possible to specify just one of the two. If both are undefined, the tool behaves equivalent to DateTime.Add and DateTime.Subtract.

The following example shows the usage of DateAdd:

public void DateAddSample()
{
  DateAdd dateAdd = new DateAdd();

  dateAdd.IncludePeriods.Add( new TimeRange( new DateTime( 2011, 3, 17 ),
                              new DateTime( 2011, 4, 20 ) ) );

  // setup some periods to exclude
  dateAdd.ExcludePeriods.Add( new TimeRange(
    new DateTime( 2011, 3, 22 ), new DateTime( 2011, 3, 25 ) ) );
  dateAdd.ExcludePeriods.Add( new TimeRange(
    new DateTime( 2011, 4, 1 ), new DateTime( 2011, 4, 7 ) ) );
  dateAdd.ExcludePeriods.Add( new TimeRange(
    new DateTime( 2011, 4, 15 ), new DateTime( 2011, 4, 16 ) ) );

  // positive
  DateTime dateDiffPositive = new DateTime( 2011, 3, 19 );
  DateTime? positive1 = dateAdd.Add( dateDiffPositive, 
                                     Duration.Hours( 1 ) );
  Console.WriteLine( "DateAdd Positive1: {0}", positive1 );
  // > DateAdd Positive1: 19.03.2011 01:00:00
  DateTime? positive2 = dateAdd.Add( dateDiffPositive, 
                                     Duration.Days( 4 ) );
  Console.WriteLine( "DateAdd Positive2: {0}", positive2 );
  // > DateAdd Positive2: 26.03.2011 00:00:00
  DateTime? positive3 = dateAdd.Add( dateDiffPositive, 
                                     Duration.Days( 17 ) );
  Console.WriteLine( "DateAdd Positive3: {0}", positive3 );
  // > DateAdd Positive3: 14.04.2011 00:00:00
  DateTime? positive4 = dateAdd.Add( dateDiffPositive, 
                                     Duration.Days( 20 ) );
  Console.WriteLine( "DateAdd Positive4: {0}", positive4 );
  // > DateAdd Positive4: 18.04.2011 00:00:00

  // negative
  DateTime dateDiffNegative = new DateTime( 2011, 4, 18 );
  DateTime? negative1 = dateAdd.Add( dateDiffNegative, 
                                     Duration.Hours( -1 ) );
  Console.WriteLine( "DateAdd Negative1: {0}", negative1 );
  // > DateAdd Negative1: 17.04.2011 23:00:00
  DateTime? negative2 = dateAdd.Add( dateDiffNegative, 
                                     Duration.Days( -4 ) );
  Console.WriteLine( "DateAdd Negative2: {0}", negative2 );
  // > DateAdd Negative2: 13.04.2011 00:00:00
  DateTime? negative3 = dateAdd.Add( dateDiffNegative, 
                                     Duration.Days( -17 ) );
  Console.WriteLine( "DateAdd Negative3: {0}", negative3 );
  // > DateAdd Negative3: 22.03.2011 00:00:00
  DateTime? negative4 = dateAdd.Add( dateDiffNegative, 
                                     Duration.Days( -20 ) );
  Console.WriteLine( "DateAdd Negative4: {0}", negative4 );
  // > DateAdd Negative4: 19.03.2011 00:00:00
}

The specialization CalendarDateAdd allows specifying the weekdays and working hours used by the addition or subtraction:

public void CalendarDateAddSample()
{
  CalendarDateAdd calendarDateAdd = new CalendarDateAdd();
  // weekdays
  calendarDateAdd.AddWorkingWeekDays();
  // holidays
  calendarDateAdd.ExcludePeriods.Add( 
             new Day( 2011, 4, 5, calendarDateAdd.Calendar ) );
  // working hours
  calendarDateAdd.WorkingHours.Add( 
          new HourRange( new Time( 08, 30 ), new Time( 12 ) ) );
  calendarDateAdd.WorkingHours.Add(
          new HourRange( new Time( 13, 30 ), new Time( 18 ) ) );

  DateTime start = new DateTime( 2011, 4, 1, 9, 0, 0 );
  TimeSpan offset = new TimeSpan( 22, 0, 0 ); // 22 hours

  DateTime? end = calendarDateAdd.Add( start, offset );

  Console.WriteLine( "start: {0}", start );
  // > start: 01.04.2011 09:00:00
  Console.WriteLine( "offset: {0}", offset );
  // > offset: 22:00:00
  Console.WriteLine( "end: {0}", end );
  // > end: 06.04.2011 16:30:00
}

Search for Calendar Periods

A CalendarPeriodCollector offers the possibility to search for certain calendar periods within given time limits. By using a ICalendarPeriodCollectorFilter, such a search can be restricted by the following criteria:

Search by years
Search by months
Search by days of months
Search by weekdays

Without a filter set, all time ranges of a period will be considered matching. Combining can be done by the following target scopes:

Years: CalendarPeriodCollector.CollectYears
Months: CalendarPeriodCollector.CollectMonths
Days: CalendarPeriodCollector.CollectDays
Hours: CalendarPeriodCollector.CollectHours

In normal mode, all time ranges of the found ranges will be combined. For example, this allows to find all hours of a day by using CalendarPeriodCollector.CollectHours.

To further constrain the result, time ranges can be defined as follows:

Which months of a year: ICalendarPeriodCollectorFilter.AddCollectingMonths
Which days of a month: ICalendarPeriodCollectorFilter.AddCollectingDays
Which hours of a day: ICalendarPeriodCollectorFilter.AddCollectingHours

By defining a time range for the hours from 08:00 to 10:00 for example, the result will only contain one single time period covering both hours (as opposed to having a time period for each hour). This proves to be a valuable (if not necessary) optimization when combining large time ranges.

The following example collects all working hours of Fridays in the month of January of several years:

public void CalendarPeriodCollectorSample()
{
  CalendarPeriodCollectorFilter filter =
                             new CalendarPeriodCollectorFilter();
  filter.Months.Add( YearMonth.January ); // only Januaries
  filter.WeekDays.Add( DayOfWeek.Friday ); // only Fridays
  // working hours
  filter.CollectingHours.Add( new HourRange( 8, 18 ) );

  CalendarTimeRange testPeriod = new CalendarTimeRange(
       new DateTime( 2010, 1, 1 ), new DateTime( 2011, 12, 31 ) );
  Console.WriteLine( "Calendar period collector of period: " +
                     testPeriod );
  // > Calendar period collector of period:
  //            01.01.2010 00:00:00 - 30.12.2011 23:59:59 | 728.23:59

  CalendarPeriodCollector collector =
          new CalendarPeriodCollector( filter, testPeriod );
  collector.CollectHours();
  foreach ( ITimePeriod period in collector.Periods )
  {
    Console.WriteLine( "Period: " + period );
  }
  // > Period: 01.01.2010; 08:00 - 17:59 | 0.09:59
  // > Period: 08.01.2010; 08:00 - 17:59 | 0.09:59
  // > Period: 15.01.2010; 08:00 - 17:59 | 0.09:59
  // > Period: 22.01.2010; 08:00 - 17:59 | 0.09:59
  // > Period: 29.01.2010; 08:00 - 17:59 | 0.09:59
  // > Period: 07.01.2011; 08:00 - 17:59 | 0.09:59
  // > Period: 14.01.2011; 08:00 - 17:59 | 0.09:59
  // > Period: 21.01.2011; 08:00 - 17:59 | 0.09:59
  // > Period: 28.01.2011; 08:00 - 17:59 | 0.09:59
}

Search for Days

In many situations, it is required to determine the next available day of work, given a number of working days. When counting through the days from a given moment in time, weekends, holidays, service and maintenance periods should be excluded.

To help with this task, the class DaySeeker is available. Analogous to the CalendarPeriodCollector, this class can be controlled with predefined filters. The following example shows the search for working days while skipping over all weekends and holidays:

The implementation of this example looks as follows:

public void DaySeekerSample()
{
  Day start = new Day( new DateTime( 2011, 2, 15 ) );
  Console.WriteLine( "DaySeeker Start: " + start );
  // > DaySeeker Start: Dienstag; 15.02.2011 | 0.23:59

  CalendarVisitorFilter filter = new CalendarVisitorFilter();
  filter.AddWorkingWeekDays(); // only working days
  filter.ExcludePeriods.Add( new Week( 2011, 9 ) );  // week #9
  Console.WriteLine( "DaySeeker Holidays: " + 
                     filter.ExcludePeriods\[ 0 \] );
  // > DaySeeker Holidays: w/c 9 2011; 28.02.2011 - 06.03.2011 | 6.23:59

  DaySeeker daySeeker = new DaySeeker( filter );
  Day day1 = daySeeker.FindDay( start, 3 ); // same working week
  Console.WriteLine( "DaySeeker(3): " + day1 );
  // > DaySeeker(3): Freitag; 18.02.2011 | 0.23:59

  Day day2 = daySeeker.FindDay( start, 4 ); // Saturday -> next Monday
  Console.WriteLine( "DaySeeker(4): " + day2 );
  // > DaySeeker(4): Montag; 21.02.2011 | 0.23:59

  Day day3 = daySeeker.FindDay( start, 9 ); // holidays -> next Monday
  Console.WriteLine( "DaySeeker(9): " + day3 );
  // > DaySeeker(9): Montag; 07.03.2011 | 0.23:59
}

Environmental Elements

Time related definitions and basic calculations are located in various utility classes:

Element	Description
`TimeSpec`	Constants for times and periods
`YearHalfyear` `YearQuarter` `YearMonth` `YearWeekType`	Enumerations for half years, quarters, months, and week types
`TimeTool`	Operations for modifications of date and time values as well as for specific time periods
`TimeCompare`	Functions for comparison of time periods
`TimeFormatter`	Formatting of time periods
`TimeTrim`	Functions to trim time periods
`Now`	Calculation of the current moment of time for the various time periods; e.g., the start time of the current calendar quarter
`Duration`	Calculation for specific time periods
`Date`	The date part of a `DateTime`
`Time`	The time part of a `DateTime`
`CalendarVisitor`	Abstract base class for iterating over calendar periods
`DateTimeSet`	Sorted list of unique moments in time
`CalendarVisitor`	Abstract base class for iterating over calendar periods
`BroadcastCalendarTool`	Calculation Tools for the broadcast calendar
`FiscalCalendarTool`	Calculation Tools for the fiscal calendar

Library and Unit Tests

The library Time Period is available in four versions:

Library for .NET 2.0 including Unit Tests
Library for .NET for Silverlight 4
Library for .NET for Windows Phone 7
o Portable Class Library for Windows Store, .NET 4, Silverlight 4, Windows Phone 7

Most of the classes are covered by NUnit tests. The source code is the same for all three variants (see below: Composite Library Development), but the Unit Tests are only available with the Portable Class Library and for the complete .NET Framework.

Creating stable working tests for time based functionality is not an easy task, because various factors influence the state of the test objects:

Differing Cultures make use of different calendars
Functionality which is based on DateTime.Now can (and most often will) result in differing behavior and test results when executed at different times
Time calculations - especially involving time periods - lead to a multitude of special cases

Considering this, it is of little surprise to find almost three times as much code in the Unit Tests as in the actual library implementation.

Source Code and Package

👉 GitHub Repository
👉 NuGet Package

Structured ASP.NET Localization

Jani Giannoudis — Thu, 17 Aug 2023 09:27:26 +0000

In the globally connected IT world, delivering software in different languages is a basic requirement. This article presents a structured approach to localizing ASP.NET applications using the Blazor template application.

Structuring localization provides the following benefits

Localized text is grouped by topic
Type safety for localization parameters
Enumeration localization
Clear translation templates

From Global to Local

To localize an application, it must be designed to be as culturally neutral as a global application. Global applications are extended by the localization of the respective culture. This separation is achieved by placing the localized texts in resource files of type .resx.

The following overview shows the localization of the sample application.

Localization is represented in Visual Studio as follows:

Localizations.csproj - Class library
- LocalizerBase.cs - Base class for all localizers
- Localizer.cs - Strater class for localization
- Resources\Localizations.resx - English (default) localization resources
- Resources\Localizations.de.resx - German localization resources
GlobalApp.csproj - Blazor server application
- Shared\*.razor - Shared components
- Pages\*.razor - Application pages

Building Localizers

All localized texts are divided thematically into localizer classes, which are derived from the base class LocalizerBase. The localized texts are accessed through the root class Localizer:

public class Localizer : LocalizerBase
{
    public Localizer(IStringLocalizerFactory factory) :
        base(factory, nameof(Localizer))
    {
        App = new(factory);
        Home = new(factory);
        Survey = new(factory);
        Counter = new(factory);
        Forecast = new(factory);
    }

    public AppLocalizer App { get; }
    public HomeLocalizer Home { get; }
    public SurveyLocalizer Survey { get; }
    public CounterLocalizer Counter { get; }
    public ForecastLocalizer Forecast { get; }
}

For each topic, a localizer is implemented to provide access to the translated resources, like the example CounterLocalizer:

public class CounterLocalizer : LocalizerBase
{
    public CounterLocalizer(IStringLocalizerFactory factory) :
        base(factory)
    {
    }

    public string Title => Localization();
    public string Click => Localization();
    public string CurrentCount(int currentCount) =>
        ApplyParameter(Localization(), 
                       nameof(currentCount), currentCount);
}

The fixed translation data is determined with the Localization() method. The translation keys Counter.Title, Counter.Click and Counter.CurrentCount are generated from the class name and the property. Translations with variable parameters generate a formatted text with the parameter name as placeholder Current count: {currentCount}.

Setup Cultures

The Culture class manages the translation culture:

Available languages
Default language
Access path to translation resources
Getting and changing the runtime language

For ASP.NET applications, the structure is not set at the application level (CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture), but at the web request thread level (CultureInfo.DefaultThreadCurrentCulture and CultureInfo.DefaultThreadCurrentUICulture).

Providing the Localizer

The Localizer is accessed through dependency injection, which is set up when the application is launched.

public class Program
{
    private static void SetupLocalization(IServiceCollection services)
    {
        services.AddLocalization(o => 
                       { o.ResourcesPath = Cultures.ResourcesPath; });
        services.AddTransient<Localizer>();
        Cultures.ApplyCulture();
    }

    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        // Add services to the container.
        builder.Services.AddRazorPages();
        builder.Services.AddServerSideBlazor();
        builder.Services.AddSingleton<WeatherForecastService>();

        // localizations
        SetupLocalization(builder.Services);

        var app = builder.Build();

        // app setup
        // ...

        app.Run();
    }
}

The SetupLocalization method performs the following steps

Register the Microsoft Localization Extensions
Register the 'Localizer' in the dependency injection
Set the default language for the current thread

Using the Localizer

The Localizer is inserted into the page using Inject and replaces the hard-coded text with a readable property or method access.

@page "/counter"
@using Localization

<PageTitle>Counter</PageTitle>

<h1>@Localizer?.Counter.Title</h1>

<p role="status">@Localizer?.Counter.CurrentCount(currentCount)</p>

<button class="btn btn-primary"
      @onclick="IncrementCount">@Localizer?.Counter.Click</button>

@code {
    private int currentCount;
    [Inject]
    private Localizer? Localizer { get; set; }

    private void IncrementCount()
    {
        currentCount++;
    }
}

The value @Localizer?.Counter.Title returns the localized title and @Localizer?.Counter.CurrentCount(currentCount) provides type safety (int).

Localizing Enumerations

Another scenario is the translation of enumerations whose localization is stored according to the Enum.<EnumTypeName>.<EnumValue> convention. The localized enumerations can be queried with Localizer.Enum<T>(T value).

@page "/"
@using Localization

<PageTitle>@Localizer?.Home.Title</PageTitle>

<h1>@Localizer?.Home.Header</h1>

@Localizer?.Home.Welcome

<SurveyPrompt Title="@Localizer?.Home.SurveyTitle" />

@Localizer?.Home.EnumLocalization
<InputSelect @bind-Value="CurrentColor">
    @foreach (var value in Enum.GetValues(typeof(Color)))
    {
        <option>@Localizer?.Enum((Color)value)</option>
    }
</InputSelect>

@code {
    [Inject]
    private Localizer? Localizer { get; set; }
    private string? CurrentColor { get; set; }

    protected override Task OnInitializedAsync()
    {
        CurrentColor = Localizer?.Enum(Color.Red);
        return base.OnInitializedAsync();
    }
}

Runtime Language Switching

Switching the language at runtime is done via the drop-down list in the header, which activates the language in the background via the Culture class:

Resource Translation

The localization project contains the localized texts (Localizations.resx) in the default language, usually English. When localizing this file into other languages, the following aspects should be considered

If the translation is for a language or country Language: de Countries: de-US or de-GB
All placeholders (count in the example above) must be included
All resources must be translated

Tools like ReSharper are helpful in finding broken translation resources.

Source Code

👉 The source code is available in the GitHub repository Giannoudis/StructuredLocalization.

Travel through Time Data

Jani Giannoudis — Thu, 10 Aug 2023 19:31:02 +0000

I love time travel movies because I am fascinated by mind games with time. The topic of time has also accompanied me for a long time in my profession, where I have dealt with complex time calculations. My last open source project was about being able to control the lifecycle of business data at the field level.

Established historization and audit trail approaches are not suitable due to additional business requirements:

Data is controlled at the field level, not the object level
Data can be changed multiple times
Data can be changed and undone retroactively
Data changes can be scheduled
Data analysis with data from the past and (back to) the future

Using an employee's salary, I would like to show how I solved the problem with time data. In the initial situation we have the employee name@domain.com with a monthly salary of 5000.

{
  "id": "name@domain.com",
  "salary": 5000
}

Time Data

In addition to the actual value, time data also contains time information with the creation date and a time period in which the value is to apply.
The illustration of the above example with time data and an additional time limit until the end of 2023:

{
  "id": "name@domain.com",
  "salary": [
    {
      "value": 5000,
      "created": "2023-01-01T00:00:00.0Z",
      "period": {
        "start": "2023-01-01T00:00:00.0Z",
        "end": "2023-12-31T23:59:59.9Z"
      }
    }
  ]
}

The time data is immutable, so a new time value is created the next time the salary is adjusted. In the following example, the salary is increased to 6000 from March to the end of August.

{
  "id": "name@domain.com",
  "salary": [
    {
      "value": 5000,
      "created": "2023-01-01T00:00:00.0Z",
      "period": {
        "start": "2023-01-01T00:00:00.0Z"
      }
    },
    {
      "value": 6000,
      "created": "2023-03-01T00:00:00.0Z",
      "period": {
        "start": "2023-03-01T00:00:00.0Z",
        "end": "2023-08-31T23:59:59.9Z"
      }
    }
  ]
}

Based on this information, the value can be determined at any point in time. Time data literally opens up new perspectives: I can freely choose a point in time and look at the data from that point on. I have named the observation date of the time values evaluation date.

With the variable evaluation date, interesting evaluations are possible:

Past view - analysis of the data as it was at an earlier point in time.
Future view - analysis of the data as it will be at a future point in time.

The following figure shows different evaluation dates for the above example:

Example for past Time Data

In this example the salary was changed on March 1, 2023, retroactive to February. The new salary of 5500 is to be valid until mid-April 2023.

{
  "id": "name@domain.com",
  "salary": [
    {
      "value": 5000,
      "created": "2023-01-01T00:00:00.0Z",
      "period": {
        "start": "2023-01-01T00:00:00.0Z"
      }
    },
    {
      "value": 5500,
      "created": "2023-03-01T00:00:00.0Z",
      "period": {
        "start": "2023-02-01T00:00:00.0Z",
        "end": "2023-04-15T23:59:59.9Z"
      }
    }
  ]
}

The query of the evaluation time data values gives the following picture:

Example for future Time Data

In this scenario, the salary has been increased to 4500 on March 1, 2023. The adjustment is effective from September through mid-October.

{
  "id": "name@domain.com",
  "salary": [
    {
      "value": 5000,
      "created": "2023-01-01T00:00:00.0Z",
      "period": {
        "start": "2023-01-01T00:00:00.0Z"
      }
    },
    {
      "value": 5500,
      "created": "2023-03-01T00:00:00.0Z",
      "period": {
        "start": "2023-08-01T00:00:00.0Z",
        "end": "2023-10-15T23:59:59.9Z"
      }
    }
  ]
}

This results in the following time data values:

Time Data with C-Sharp

The example contains the following types

TimeValue - contains the time data
TimeField - time field with multiple time data
Employee - employee with salary as time data
Extensions - time data calculations

public class TimeValue<T>
{
    public DateTime Created { get; set; }
    public ValuePeriod Period { get; set; }
    public T Value { get; set; }
}

public class TimeField<T> : Collection<TimeValue<T>>
{
}

public class Employee
{
    public string? Id { get; set; }
    public TimeField<decimal>? Salary { get; set; }
}

public static class Extensions
{
    public static bool IsInside<T>(this TimeValue<T> value,
                                   DateTime evaluationDate) =>
        evaluationDate >= value.Period.Start && 
        evaluationDate <= value.Period.End;

    public static TimeValue<T>? GetTimeValue<T>(
                this TimeField<T> values, DateTime evaluationDate)
    {
        if (!values.Any())
        {
            return default;
        }

        var timeValues = values.
            // remove values created after the evaluation date
            Where(x => x.Created <= evaluationDate &&
                       // remove outside periods
                       x.IsInside(evaluationDate)).ToList();
        if (!timeValues.Any())
        {
            return default;
        }

        // select the evaluated value (last created)
        var timeValue = timeValues.OrderByDescending(x => 
                                            x.Created).First();
        return timeValue;
    }
}

The algorithm for calculating the current time value GetTimeValue first excludes the time values that were created after the evaluation time or are irrelevant (IsInside). From the remaining time values, the most recent one is selected.

Time Data Mapping

In relational models, time data can be kept in separate entities/tables. If the amount of time data is small, the simplest scenario is to have a separate table containing the time data, for example, EmployeeSalary. For larger amounts of time data, it is recommended to group them into tables:

By data type e.g. TimeDataDecimal, TimeDataInteger...
By object e.g. EmployeeTimeData.
- One column per data type
- One text column with JSON representation

To convert time data to traditional data, the time data value is determined from the current time. The conversion of traditional values to time data is represented by a period that starts immediately and is unbounded.

GitHub Repository

If you want to invest more of your time, you can take a look at this example on GitHub.

Have a good time.