Table of Contents

Globalization & Calendars - Guides

Recipe-style walk-throughs for the calendar package family - the Bodu.Globalization.Calendar runtime, its companions (Builder, DependencyInjection, Plugins, Caching, Tool, Build), the five regional data packs, and the independent Bodu.Globalization.Recurrence sibling. This page is the topic-level map; the complete guide lists live in the calendar guides index and the Recurrence guides index.

If you are new to the family, start with the topic overview for the package decision table and the topic concepts for the shared vocabulary, then come back here for the hands-on material.

The guides

Overview

The full guide index for the calendar family - resolution pipeline, namespace map, and every walk-through grouped by namespace.

Using NotableDateService

The main entry point - loading a resource, resolving for a date, range, or year, filtering by territory and category, and the reloadable runtime-swap workflow.

Authoring notable date rules

Writing rule documents in XML / JSON - definitions, rules, strategies, importing the bundled common catalogues with <Use> directives, and layering ID-targeted <Overrides>.

Working-day arithmetic

The Bodu.Extensions surface over DateOnly / DateTime / DateTimeOffset - IsWorkingDay, AddWorkingDays, WorkingDaysBetween, snap operations, and the WeekPattern working week.

Calendar data packs

The regional companion assemblies - CreateService / LoadResource factories, territory coverage, and composing several regions into one service.

Date calculation algorithms

The six resolution strategies and the built-in <Algorithm key="…"> keys - Easter, equinoxes, Qingming, Vesak, Losar, Matariki, Hindu festivals - plus a custom-algorithm walk-through.

Companion packages

Authoring with the notable-date builder

The fluent C# peer of XML / JSON authoring - NotableDateDocumentBuilder assembles definitions, rules, policies, imports, and overrides, then serializes, saves, or builds a resource.

Calendar dependency injection

services.AddNotableDateService(...), the resource-factory overload, and AddReloadableNotableDateService(...) for the runtime-swap workflow.

Building and extending the service

Composing the service with collaborators - algorithm and adjustment registries, collision resolvers, localizers, providers, and the trust-gated plugin system.

Calendar plugin trust

What the deny-by-default plugin gate validates, what each bundled trust policy does and does not check, and how a rejected or failing plugin surfaces.

Caching notable dates

The Bodu.Globalization.Calendar.Caching read-through decorator - per-territory, per-civil-year entries, the in-memory / file / SQLite / distributed backends, warm-up, and the DI registration.

Builder round-trip guarantees

Exactly what the builder's XML and JSON serialization, parsing, and resource materialization guarantee - and what they do not.

Calendar validation diagnostics

The stable BODU-CAL-* code catalogue, severities, and the collect-mode lint surface (TryLoad, Validate, TryBuild).

Binary rule packs

Compiling validated documents to sealed .bcal packs - the trim- and AOT-friendly load path - with the bodu-calendar tool and the MSBuild integration.

Recurrence and scheduling

Recurrence and scheduling

Bodu.Globalization.Recurrence - RFC 5545 recurrence rules and rule sets, cron expressions, and anchored intervals behind one next / previous occurrence surface; an independent sibling that composes with the calendar from outside.

The data

Notable-date catalogue

What notable dates the calendar resources include and how regions and territories differ - generated from the XML, organized by theme and by region, with a cross-region comparison matrix.

Suggested reading path

  1. Using NotableDateService - resolve and filter dates with a data-pack service; the 80 % case.
  2. Calendar data packs - pick your regions and understand territory coverage.
  3. Working-day arithmetic - business-day math over the resolved dates.
  4. Authoring notable date rules or the builder guide - when the shipped data is not enough.
  5. Date calculation algorithms and Building and extending the service - the extensibility seams, including plugins.

Where to go next