TimeSpans sind eine großartige Funktion von .NET und im gesamten Ökosystem weit verbreitet. Aber was wäre, wenn wir sie etwas benutzerfreundlicher gestalten könnten, wenn wir sie in Konfigurationsdateien definieren möchten?

TimeSpans kommen beim Schreiben von Code für .NET häufig vor, da sie einer Vielzahl von Zwecken dienen können. Einige Beispiele hierfür sind unter anderem:

• Wartezeiten/Verzögerungen definieren
• Timeouts definieren
• Eine Aufgabe für später planen
• Daten manipulieren

Einige Beispiele dafür, warum wir möchten, dass diese Werte konfigurierbar sind, könnten sein:

…Eine Auszeit? Möglicherweise möchten Sie, dass dies in Testumgebungen etwas länger dauert, da Sie weniger leistungsstarke und langsamere Maschinen verwenden.

…eine Aufgabe planen? Möglicherweise möchten Sie, dass dies in Testumgebungen sehr schnell geschieht, damit Sie sicher sein können, dass es ausgelöst wurde, in Produktionsumgebungen jedoch länger.

…oder vielleicht reagieren Sie einfach auf die sich ändernden Anforderungen Ihrer Anwendung.

Wie konfigurieren wir also TimeSpans?

Beginnen wir zunächst mit den Standard-Microsoft-Erweiterungsbibliotheken. Microsoft hat mehrere Pakete für die Konfiguration erstellt, die es uns ermöglichen, diese problemlos über mehrere Quellen aufzubauen und uns dann verschiedene APIs zum Abrufen und Binden unserer Konfiguration an starke Typen zur Verfügung zu stellen.

In diesem Beitrag werden wir die APIs IConfigurationBuilder und IConfiguration wiederverwenden, um unsere TimeSpans zu konfigurieren. Diese APIs werden vom Host-Builder standardmäßig in Asp.Net Core verwendet, sodass Sie möglicherweise bereits mit ihnen vertraut sind.

Dieser Beitrag wird sich nicht im Detail auf diese APIs konzentrieren. Wenn Sie also eine ausführlichere Erklärung dazu wünschen oder wissen möchten, wie man sie verwendet, schauen Sie sich die Dokumentation für Microsoft.Extensions.Configuration an .

Die Konfigurationswerte Ihres TimeSpan können über jede gewünschte Konfigurationsquelle gespeichert werden. Der Einfachheit halber und weil sie nicht „geheim“ sind, verwenden wir jedoch appsettings.json-Dateien. Das Paket, das Sie hierfür benötigen, ist Microsoft.Extensions.Configuration.Json

Unser Code zum Erstellen dieser IConfiguration für dieses Beispiel ist so einfach wie:

ReadableTimeSpan.EnableConfigurationBinding();

var configuration = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .Build();

Anschließend können wir unsere TimeSpan in unserer JSON-Datei definieren. Das wird standardmäßig im String-Format unterstützt, ist aber nicht sehr intuitiv zu lesen.

Nehmen Sie zum Beispiel Folgendes:

{
  "Timeout": "00:01:00"
}

• Es kann unklar sein, was dieser Wert darstellt
• Es ist sehr leicht, einen Fehler zu machen – menschliches Versagen passiert ständig

Diejenigen unter Ihnen, die mit TimeSpan-Zeichenfolgenformaten vertraut sind, wissen vielleicht, was dieser Wert darstellt (aus Gründen der Transparenz beträgt er 1 Minute), aber für jüngere oder weniger vertraute Entwickler ist das nicht so offensichtlich.

Noch verwirrender kann es werden, wenn Sie anfangen möchten, Tage, Stunden, Minuten, Sekunden und Millisekunden zu mischen.

{
  "Timeout": "1.12:10:05.100"
}

ReadableTimeSpan

Um dieses Problem zu lösen, habe ich eine Bibliothek namens ReadableTimeSpan erstellt .

Auf diese Weise können Sie die TimeSpan-Konfiguration in einem Format definieren, das leicht zu lesen und zu verstehen ist. Die Bibliothek finden Sie auf GitHub unterhttps://github.com/thomhurst/ReadableTimeSpan

Um dies in Ihrem Projekt zu verwenden, fügen Sie einfach das NuGet-Paket TomLonghurst.ReadableTimeSpan hinzu und rufen Sie vor dem Hinzufügen zu Ihrem IConfigurationBuilder die statische Methode auf:

ReadableTimeSpan.EnableConfigurationBinding()

Der Code ist fertig – er lässt sich ganz einfach einrichten und jetzt können Sie mit der Definition leicht lesbarer Konfigurationen beginnen. Es gibt Optionen für Kurzschrift oder Langschrift sowie verschiedene Trennzeichen zur Unterscheidung verschiedener Einheiten. Besprechen Sie mit Ihren Kollegen, welche Syntax Sie bevorzugen würden.

Die vollständigen Optionen sind in der GitHub-Readme-Datei verfügbar, aber hier sind einige Beispiele, wie Sie jetzt Ihre Konfiguration schreiben könnten:

{
  "Timeout": "1 day and 12 hours and 10 minutes and 5 seconds and 100 milliseconds"
}
{
  "Timeout": "1d + 12h + 10m + 5s + 100ms"
}
{
  "Timeout": "1day|12hr|10mins|5secs|100mils"
}

Binden Sie nun Ihre Konfiguration an Ihre starken Typen und verwenden Sie Ihre TimeSpans!

var timeout = configuration.Get<TestOptions>().Timeout;

Sie können ReadableTimeSpan auch außerhalb der Konfigurationsbindung verwenden. Sie verfügt über ähnliche APIs wie die reguläre TimeSpan-Klasse und stellt Ihnen die Methoden Parse und TryParse zur Verfügung.

var timespan = ReadableTimeSpan.Parse("1 sec & 500ms");
if (ReadableTimeSpan.TryParse("1 sec & 500ms", out var timeSpan))
{
    return timeSpan;
}

Wenn Sie ReadableTimeSpans aus JSON serialisieren oder deserialisieren müssen, gibt es Pakete, die Konverter sowohl für Newtonsoft- als auch für System.TextJson-Serialisierer bereitstellen.

Dies sind jeweils:

• TomLonghurst.ReadableTimeSpan.Newtonsoft.Json
• TomLonghurst.ReadableTimeSpan.System.Text.Json

ToReadableString

Wenn Sie einen TimeSpan in eine lesbare Zeichenfolge ausgeben möchten, gibt es als Bonus eine Erweiterungsmethode ToReadableString. Dies funktioniert auch bei regulären TimeSpans.

var readableString = myTimespan.ToReadableString();

Obwohl es sich um eine kleine und einfache Bibliothek handelt, kann sie die Lesbarkeit verbessern und möglicherweise Fehler reduzieren. Wenn Sie es nützlich oder interessant fanden, geben Sie ihm bitte einen Stern auf GitHub, teilen Sie es und teilen Sie mir Ihre Meinung mit!