17. Mai 2021
Lesedauer 12 Min.
Feiertagsrechner
Feiertage berechnen mit Nager.Date
Das Handling von Datumsangaben ist mühsam und fehleranfällig. Hier hilft Nager.Date.
Die Berechnung mancher Feiertage ist einfach, zum Beispiel für die festen oder nicht beweglichen. Neujahr ist immer am 1. Januar, der Tag der Arbeit am 1. Mai und der erste Weihnachtsfeiertag am 25. Dezember.Bei den beweglichen Feiertagen wird die Sache schon komplizierter. Und erst recht, wenn freie Tage im Ausland berücksichtigt werden sollen. So ist zum Beispiel der 7. April 2021 der Women’s Day in Mosambik und der 9. April 2021 der Martyrs’ Day in Tunesien.Vieles wird beispielsweise vom Ostersonntag aus berechnet. Gründonnerstag ist der Ostersonntag (OS) minus drei Tage. Karfreitag ist OS minus zwei Tage. Pfingstsonntag ist Ostersonntag plus 49 Tage und so weiter. Der Ostersonntag lässt sich mit der gaußschen Osterformel [1] nach Carl Friedrich Gauß berechnen (siehe Kasten Die Osterformel), und der Buß- und Bettag hat eine eigene Formel.Alles in allem ist das aufwendig und kostet Zeit. Dabei sind die Anwendungsfälle zahlreich: zum Beispiel wenn es gilt, die langen Wochenenden für einen Urlaub zu ermitteln, den letzten Montag in einem Monat oder den letzten Bankarbeitstag von einem Datum aus zu berechnen.Daher ist der Einsatz einer Bibliothek mindestens eine Überlegung wert. Es gibt mittlerweile zahlreiche Implementierungen, die alle ihre Vor- und Nachteile haben. Zudem gibt es noch verschiedene Herangehensweisen an das Problem, wenn doch keine Bibliothek zum Einsatz kommen soll oder wenn die Daten beispielsweise zwischengespeichert werden müssen. Darauf geht der Artikel gegen Ende ein.Der Hauptfokus in diesem Artikel liegt aber auf der Bibliothek Nager.Date [2]. Sie verspricht, die zahlreichen Fallstricke und Probleme bei der Feiertagsberechnung zu lösen. Nicht nur in Form einer Bibliothek mit .NET-API, sondern auch über eine REST-Schnittstelle und als Self-hosted-Variante. Was die Bibliothek alles kann, zeigt der Artikel im weiteren Verlauf.
Die Osterformel
Die sogenannte Osterformel wurde von Carl Friedrich Gauß entwickelt und öfters überarbeitet. Die Formel besteht aus mehreren Teilen. Zudem sind zwei Konstanten, <em>M</em> und <em>N</em>, im Einsatz. Diese sind Hilfszahlen für den Gregorianischen Kalender und ändern sich im 100-Jahre-Rhythmus. Die Herleitung ist an dieser Stelle nicht so wichtig. Zwischen den Jahren 2000 und 2099 werden diese Konstanten auf <em>M = 24</em> und <em>N = 5</em> festgelegt.
Was ist Nager.Date?
Nager.Date ist eine in C# geschriebene Bibliothek für das .NET-Universum. Die Kernfunktionen lassen sich am besten damit beschreiben, dass mit Nager.Date Feiertage und Wochenenden abgefragt werden können. Zu einem gegebenen Datum gibt die Bibliothek somit die Information zurück, ob es ein Feiertag, ein Wochenende oder ein ganz normaler Tag ist. Auch die Abfrage nach einem spezifischen Tag von einem Datum aus oder die Abfrage von langen Wochenenden sind mit Nager.Date realisierbar.Nager.Date gilt als performant und unterstützt über 100 Länder. Damit ist die Bibliothek insbesondere in Projekten sehr interessant, in denen nicht nur deutsche Feiertage berechnet werden müssen.Zudem wird Nager.Date nicht nur als Bibliothek angeboten, sondern besitzt darüber hinaus ein öffentliches API, das auch in Form eines Docker-Containers zum Selbsthosten zur Verfügung steht.Wer einen Überblick über die unterstützten Länder bekommen möchte, findet eine gute Übersicht auf der Website von Nager.Date [3]. Dabei wird deutlich, dass Europa mit über 98 Prozent am besten abgedeckt ist, gefolgt von Amerika mit über 57 Prozent, Afrika mit über 23 Prozent und Asien mit 14 Prozent. Ozeanien und die Antarktis liegen darunter.Interview mit Tino Hager
<em>Wann hat deine Arbeit an Nager.Date begonnen, und kannst du uns den Hauptgrund nennen, der zum Start beigetragen hat? </em>
Installation
Die Installation von Nager.Date ist kein Problem. Es steht ein NuGet-Paket zur Verfügung, um die Bibliothek zum eigenen Projekt hinzuzufügen. Zudem existiert ein öffentliches API, implementiert als REST-Schnittstelle, und ein Docker-Container, falls zu viele API-Anfragen geplant sind und daher eine selbstgehostete Lösung zu bevorzugen ist. Beim Schreiben dieses Artikels war die Version 1.28.2 vom März 2021 aktuell. Die Website [2] zum Projekt erklärt, welche Funktionen und Länder zur Verfügung stehen. Eine eigene Unterseite [4] zeigt auf, wie das API aufgebaut ist. Darüber hinaus existiert eine mit Swagger erstellte eigene Schnittstellendokumentation [5] ebenfalls als Unterseite zur Projektwebsite.Der Code zu Nager.Date ist auf GitHub [6] verfügbar. Die Bibliothek ist Open Source und steht unter der MIT-Lizenz. Der hauptverantwortliche Entwickler von Nager.Date ist Tino Hager [7] aus Österreich, der die Entwicklung an Nager.Date bereits im Jahr 2014 gestartet hat. Im Rahmen dieser Kolumne gab es bereits die Vorstellung des Projekts Nager.PublicSuffix [8], das ebenfalls von Tino initiiert wurde.Die Beispielanwendung zum Artikel ist mit .NET Core 3.1 als Konsolenanwendung realisiert, was keinerlei Probleme verursacht hat.Abfrage von Feiertagen
Wie schon erwähnt, lässt sich Nager.Date im Code als Bibliothek oder über das REST-API als Online- beziehungsweise selbst gehostete Variante in Form eines Docker-Containers einbinden. Zu diesem REST-API gibt es auch NPM-Pakete, die allerdings nur die Nutzung des API kapseln. Ob das eine gute Idee ist, bleibt dahingestellt, denn das Original-API kann auch einfach abgefragt werden. Die Schnittstellen dieser unterschiedlichen Implementierungen sind vergleichbar bis identisch. Es gibt die Möglichkeit, zu einem Jahr und einem Länderkennzeichen die Feiertage zu erhalten. Der REST-Endpunkt lautet dazu/Api/v2/PublicHolidays
/{year}/{countryCode}
Im .NET-Code ist dafür
DateSystem.GetPublicHoliday(...)
zuständig. Die zusätzliche Angabe eines Start- und eines End-Datums ermöglicht die Eingrenzung der zurückgelieferten Daten. Auf diese Weise kann auch für einen einzelnen Tag geprüft werden, ob es sich um einen Feiertag handelt. Ein Aufruf der Schnittstelle
/Api/v2/IsTodayPublicHoliday/{countryCode}
ermittelt, ob es sich bei dem aktuellen Tag und dem übergebenen Länderkennzeichen um einen Feiertag handelt. Das ist für Geräte des Internets der Dinge spannend. Auch Telefonanlagen können davon profitieren, um beispielsweise festzustellen, ob die Mailbox aktiv geschaltet werden soll oder nicht. Dazu muss nur der Statuscode ausgewertet werden. Liefert ein Aufruf 200 zurück, ist der aktuelle Tag ein Feiertag. Bei der Rückgabe 204 ist es kein Feiertag.Im .NET-Code existiert dafür die Methode
DateSystem.IsPublicHoliday(...)
die es zudem erlaubt, ein Datum zu übergeben. Darüber hinaus gibt es zahlreiche Schnittstellen, um den nächsten Feiertag für ein Länderkennzeichen oder weltweit zu ermitteln, für ein Datum und ein Länderkennzeichen zu prüfen, ob es sich um ein langes Wochenende handelt, und um die verfügbaren Länder zu ermitteln, die von Nager.Date unterstützt werden.Listing 1 zeigt ein Beispiel dafür, wie die Feiertage für ein gesamtes Jahr ermittelt werden können. Bild 1 zeigt die Konsolenausgabe von JetBrains Rider.
Listing 1: Feiertage für ein Land für ein ganzes Jahr
var publicHolidays = <br/> DateSystem.GetPublicHoliday(2021, "DE"); <br/><br/>foreach (var publicHoliday in publicHolidays) <br/>{ <br/> Console.WriteLine( <br/> $"{publicHoliday.Date}, <br/> {publicHoliday.LocalName}, <br/> {publicHoliday.Name}, {publicHoliday.Fixed}, " + <br/> $"{publicHoliday.Global}, <br/> {publicHoliday.Type}"); <br/>} 
Die Ausgabe von Feiertagenfür das Jahr 2021 auf der Konsole in JetBrains Rider(Bild 1)
Autor
In diesem Beispiel werden Informationen wie das Datum, der lokale Name des Feiertags im jeweiligen Land, in diesem Fall auf Deutsch, der englische Name, sowie die Informationen, ob es sich um einen fixen Feiertag, einen globalen Feiertag und um welchen Typ es sich handelt, ausgegeben. Letzteres gibt an, ob es sich um einen öffentlichen Feiertag oder zum Beispiel einen freien Tag für Schulen handelt.Bei dem Beispiel fällt auf, dass der Ostersonntag nicht zurückgegeben wird. Das liegt daran, dass die Beispielabfrage für ganz Deutschland durchgeführt wurde. Da der Ostersonntag immer ein Sonntag ist, wird dieser nicht als Feiertag geführt. Laut Wikipedia führt nur ein Bundesland, nämlich Brandenburg, den Ostersonntag offiziell als Feiertag. In Hessen ist es beispielsweise so, dass jeder Sonntag als gesetzlicher Feiertag gilt.
Abfrage von spezifischen Tagen
Wer nicht ein komplettes Jahr abfragen möchte, kann bei der gleichen Methode eine Datumsspanne angeben. Listing 2 zeigt dazu ein Beispiel. Die Methode erlaubt es zudem, die Datumsspanne auf ein einziges Datum festzulegen:Listing 2: Feiertage für ein Land in einem Bereich
var startDate = new DateTime(2021, 4, 1); <br/>var endDate = new DateTime(2021, 4, 30); <br/>var publicHolidaysRange = <br/> DateSystem.GetPublicHoliday(<br/> startDate, endDate, CountryCode.DE); <br/><br/>foreach (var publicHoliday in publicHolidaysRange) <br/>{ <br/> Console.WriteLine( <br/> $"{publicHoliday.Date}, <br/> {publicHoliday.LocalName}, <br/> {publicHoliday.Name}, {publicHoliday.Fixed}, " + <br/> $"{publicHoliday.Global}, <br/> {publicHoliday.Type}"); <br/>} var startDate = new DateTime(2021, 4, 2);
var endDate = new DateTime(2021, 4, 2);
Wenn es an diesem Tag einen Feiertag gibt, wird dieser in diesem Beispiel, wie die vorherigen Beispiele auch, auf der Konsole ausgegeben:
02.04.2021 00:00:00, Karfreitag, Good Friday,
False, True, Public
Alternativ lässt sich über die IsPublicHoliday-Methode prüfen, ob ein Tag ein Feiertag ist:
var date = new DateTime(2021, 4, 5);
if (DateSystem.IsPublicHoliday(date, CountryCode.DE)) {
Console.WriteLine("Dieser Tag ist ein Feiertag!");
}
Das liefert aber nur zurück, ob es sich um einen Feiertag handelt oder nicht, und nicht, um welchen Feiertag es sich handelt.Eine sehr ähnliche Vorgehensweise lässt sich nutzen, um abzufragen, ob ein Datum auf ein Wochenende fällt:
var weekendDate = new DateTime(2021, 4, 4);
if (DateSystem.IsWeekend(weekendDate, CountryCode.DE)) {
Console.WriteLine("Dieser Tag ist ein Wochenende!");
} Weitere Abfragemöglichkeiten
Nager.Date bietet über die Methoden FindDay, FindDayBefore, FindDayBetween und FindLastDay noch weitere Abfragen an. FindDay ermöglicht es, nach einem bestimmten Wochentag zu suchen, der als Nächstes vom angegebenen Startdatum aufzufinden ist, zum Beispiel den nächsten Freitag nach dem 7. April 2021:var day = DateSystem.FindDay(2021, 4, 7,
DayOfWeek.Friday);
Zurückgeliefert wird korrekterweise der 9. April 2021.Ähnlich, aber mit einer Rückwärtssuche, agiert die Methode FindDayBefore. Sie sucht nach dem spezifischen Wochentag rückwärts vom angegebenen Datum aus:
var dayBefore = DateSystem.FindDayBefore(2021, 4, 7,
DayOfWeek.Friday);
In diesem Fall wird der 2. April 2021 zurückgeliefert.Ebenfalls sehr nützlich sind die Methoden FindDayBetween und FindLastDay. Erstgenannte sucht einen Wochentag zwischen zwei Datumsangaben. Letztgenannte sucht den letzten Wochentag in einem Monat. Im folgenden Beispiel den letzten Montag im April 2021:
var lastMonday = DateSystem.FindLastDay(2021, 4,
DayOfWeek.Monday);
Ebenfalls in vielen Anwendungsszenarien nützlich ist die Methode GetLongWeekend. Sie ermittelt die langen Wochenenden, die sich durch Feiertage ergeben können. Ein Aufruf für das Jahr 2021 ermittelt davon acht Stück:
var longWeekends =
DateSystem.GetLongWeekend(2021, CountryCode.DE);
Zum Beispiel zwischen dem 13. Mai 2021 und 16. Mai 2021. Dort gibt es insgesamt vier Tage. Interessant ist die Angabe, ob bei dem langen Wochenende ein Brückentag notwendig ist. Bei dem genannten Beispiel von 13. bis zum 16. Mai 2021 ist das der Fall, da am Freitag, dem 14. Mai 2021 Urlaub genommen werden muss.Die zuvor beschriebenen Beispiele und zurückgelieferten Daten des .NET-API stehen auch über die REST-Schnittstelle zur Verfügung.In der mit Swagger erstellten Dokumentation [5] werden die Data Transfer Objects (DTOs) als Schemata aufgeführt, die von den Endpunkten genutzt beziehungsweise zurückgeliefert werden. Insbesondere die DTOs LongWeekendDto und PublicHolidayDto liefert die Informationen zurück, die in den vorherigen Beispielen genutzt wurden.
Nutzung des REST-API
Das REST-API [4] von Nager.Date zu nutzen ist ebenso einfach wie die vorherigen C#-Beispiele. Die Dokumentation zum API beschreibt die Möglichkeit sehr gut und detailliert mit Beispielen, sowie die Möglichkeit, sie direkt online auszuführen. Das folgende Beispiel ist mit Postman entstanden. Bild 2 zeigt die Abfrage des folgenden GET-Requests:
Beispiel-Requestzur Abfrage der Feiertage für das Jahr 2021 in Deutschland über das öffentliche API(Bild 2)
Autor
https://date.nager.at/api/v2/publicholidays/2021/DE
Zurückgeliefert werden alle Feiertage im JSON-Format mit den gewohnten Daten, die auch schon in der C#-Version zur Verfügung standen:
{
"date": "2021-04-05",
"localName": "Ostermontag",
"name": "Easter Monday",
"countryCode": "DE",
"fixed": false,
"global": true,
"counties": null,
"launchYear": 1642,
"type": "Public"
}
Die Macher von Nager.Date bitten darum, dass dieses öffentliche API nur dann genutzt wird, wenn weniger als 50 Requests pro Tag benötigt werden.Wer mehr nutzen oder den Service lieber selbst anbieten möchte, kann die Self-hosted-Variante von Nager.Date nutzen. Dafür steht ein Docker-Container auf der Dockerhub-Website zur Verfügung.Über den folgenden Aufruf lässt sich der Container herunterladen und starten:
docker run -e "EnableCors=true"
-e "EnableIpRateLimiting=false"
-e "EnableSwaggerMode=true" -p 80:80 nager/nager-date
Anschließend steht das REST-API direkt unter der localhost-Adresse zur Verfügung:
localhost:80/api/v2/publicholidays/2020/DE
Alternativ lässt sich über Swagger ein Client für das API erzeugen:
docker run --rm -v C:\Temp:/local
swaggerapi/swagger-codegen-cli-v3 generate
-i https://date.nager.at/swagger/v1.0/swagger.json
-l csharp-dotnet2 -o /local/out
Auch das lief im Test problemlos.
Alternative Projekte
Wer Nager.Date nicht einsetzen möchte oder kann, findet etliche alternative Bibliotheken dazu.Für PHP gibt es beispielsweise die Bibliothek Yasumi [9], die nach dem japanischen Wort für Feiertag benannt ist. Das Projekt [10] wird regelmäßig gepflegt und unterstützt mittlerweile 37 Länder und über 100 sogenannter Unterbereiche (Subdivisions). Mit diesen Unterbereichen sind verschiedene Regierungszonen in den jeweiligen Ländern gemeint, die sich auf die Feiertage auswirken können – wie etwa die Bundesländer in Deutschland. Beim Schreiben dieses Artikels ist Version 2.3.0 aus dem Juni 2020 die neueste Version.Eine ebenso gut gepflegte Bibliothek für JavaScript ist date-holidays [11]. Unterstützt werden beim Schreiben dieses Artikels über 140 Länder inklusive vieler Staaten und Regionen. Das Projekt [12] unterstützt zahlreiche Browser und lässt sich so konfigurieren, dass nur ausgewählte Länder zur Verfügung stehen. Auf diese Weise wird der Bedarf an Speicherplatz reduziert, was für Webprojekte mitunter enorm wichtig ist.Für Java steht Jollyday [13] zur Verfügung, das weniger aktuell zu sein scheint als die beiden vorherigen Bibliotheken. Unterstützt werden über 60 Länder. Laut Readme des GitHub-Projekts ist ein neuer Branch in Planung, der das Jakarta XML Binding ersetzen möchte. Beim Schreiben dieses Artikels scheint das aber noch nicht umgesetzt zu sein.Für das .NET Framework existiert neben Nager.Date noch die Bibliothek Holiday [14]. Auch diese Bibliothek ist nicht ganz so gepflegt wie die ersten beiden, was auf den ersten Blick aber kein Problem zu sein scheint, denn die beim Schreiben des Artikels zuletzt veröffentlichte Version 2.3.0.0 ist aus dem November 2020. Unterstützt werden über 20 Länder mit einem starken Fokus auf Europa.Das API ist vergleichbar zu Nager.Date. Etwas befremdlich sieht die Designentscheidung aus, die verschiedenen Länder in eigene Kalender auszulagern, die dann von der Bibliothek herangezogen werden, anstatt ein Länderkennzeichen oder Ähnliches zu nutzen. Das scheint den Einsatz der Bibliothek in Szenarien mit verschiedenen Ländern unnötig zu verkomplizieren.Wer unter Python auf der Suche nach einer Bibliothek ist, darf beispielsweise zwischen python-holidays [15] und Workalendar [16] auswählen. Beide Bibliotheken sind sehr aktuell. Bei python-holidays [17] ist die zuletzt genannte Version die 0.11.1 von Anfang April 2021, und bei Workalendar [18] ist das der Release von Version 15.1.0 aus dem März 2021. Die erstgenannte Bibliothek unterstützt über 30, die letztgenannte Bibliothek über 50 Länder.Diese kleine Übersicht verdeutlicht, dass Nager.Date vom Funktionsumfang ziemlich weit vorne ist. Insbesondere bei der Unterstützung von Ländern, Staaten und Regionen kann keine andere Bibliothek mithalten.Weitere Dienste
Neben den genannten Projekten, die als Bibliotheken oder Module zur Verfügung stehen, gibt es zudem zahlreiche öffentliche APIs. Viele von diesen besitzen einen noch deutlich größeren Funktionsumfang als Nager.Date, zumindest was die unterstützten Länder betrifft.Das Working Days API [19] liefert zum Beispiel die Anzahl der Arbeitstage, Wochentage und eine Liste der Feiertage ab einem Datum zurück. Das Calendarific Global Holidays API [20] erlaubt den Zugriff auf die Datenbank von Calendarific und ermöglicht es so, auf die Feiertage von über 200 Ländern zuzugreifen. Von diesen Beispielen gibt es noch zahlreiche weitere – zu viele, um sie hier alle aufzuführen. Spezielle Übersichtsseiten [21] und Blogposts bieten einen guten ersten Eindruck, welche APIs es gibt.Fazit
Nager.Date ist eine ausgezeichnete Bibliothek. Der Funktionsumfang ist zwar überschaubar, passt aber sehr gut zum Anwendungsfall. Die Dokumentation ist zudem gut und die verschiedenen Möglichkeiten, Nager.Date einzusetzen, vervielfachen die Anwendungsfälle noch einmal.Zudem ist der Umfang der unterstützten Länder, Staaten und Regionen in Nager.Date ebenfalls sehr groß. Wer insbesondere mit Europa und Amerika zu tun hat, kann Nager.Date sicherlich gut einsetzen. Bei vielen anderen Ländern hat auch diese Bibliothek noch Nachholbedarf. Dennoch ist die Rate der unterstützten Länder deutlich höher als bei den anderen erwähnten Open-Source-Bibliotheken.Alles in allem hat sich Nager.Date eine Empfehlung und ein „Sehr gut“ verdient. Wer viel mit Feiertagen zu tun hat, darf dieser Bibliothek gerne eine Chance geben.Fussnoten
- Die Osterformel auf Wikipedia, https://de.wikipedia.org/wiki/Gau%C3%9Fsche_Osterformel
- Die offizielle Projektwebsite zu Nager.Date, https://date.nager.at/
- Die Übersicht der unterstützten Regionen von Nager.Date, https://date.nager.at/Home/RegionStatistic
- Informationen zum Nager.Date API, https://date.nager.at/Api
- Die Schnittstellendokumentation (Swagger) zum Nager.Date API, https://date.nager.at/swagger/index.html
- Das Nager.Date Repository auf GitHub, https://github.com/nager/Nager.Date
- Das Profil von Tino Hager auf GitHub, https://github.com/tinohager
- Fabian Deitelhoff, Domains nachschlagen, dotnetpro 10/2019, Seite 72 f., http://www.dotnetpro.de/A1910Frameworks
- Das Yasumi Repository auf GitHub, https://github.com/azuyalabs/yasumi
- Die offizielle Projektwebsite zu Yasumi, https://www.yasumi.dev/
- Das date-holidays Repository auf GitHub, https://github.com/commenthol/date-holidays
- Die offizielle Projektwebsite zu date-holidays, https://commenthol.github.io/date-holidays/
- Das Jollyday Repository auf GitHub, https://github.com/svendiedrichsen/jollyday
- Das Holiday Repository auf GitHub, https://github.com/martinjw/Holiday
- Das python-holidays Repository auf GitHub, https://github.com/dr-prodigy/python-holidays
- Das Workalendar Repository auf GitHub, https://github.com/peopledoc/workalendar
- Die offizielle Projektwebsite zu python-holidays, https://pypi.org/project/holidays/
- Die offizielle Projektwebsite zu Workalendar, https://peopledoc.github.io/workalendar/
- Informationen zum Working Days API, https://api.workingdays.org/1.2/api-documentation.php
- Informationen zum Calendarific Global Holidays API, https://calendarific.com/api-documentation
- Übersichtsseite zu weiteren APIs für Ferientage, https://www.programmableweb.com/news/8-top-apis-holidays/brief/2019/10/20
- Material.Blazor, https://github.com/Material-Blazor/Material.Blazor
- Our Umbraco, https://github.com/umbraco/OurUmbraco
