Wat is TimeProvider?

Artikel
12/12/2024

System.TimeProvider is een abstractie van tijd die een moment in de tijd als DateTimeOffset type biedt. Door TimeProviderte gebruiken, zorgt u ervoor dat uw code testbaar en voorspelbaar is. TimeProvider is geïntroduceerd in .NET 8 en is ook beschikbaar voor .NET Framework 4.7+ en .NET Standard 2.0 als een NuGet-pakket.

De klasse TimeProvider definieert de volgende mogelijkheden:

Biedt toegang tot de datum en tijd via TimeProvider.GetUtcNow() en TimeProvider.GetLocalNow().
Tijdstempels met hoge frequentie met TimeProvider.GetTimestamp().
Meet de tijd tussen twee tijdstempels met TimeProvider.GetElapsedTime.
Timers met hoge resolutie, inclusief TimeProvider.CreateTimer(TimerCallback, Object, TimeSpan, TimeSpan).
Haal de huidige tijdzone op met TimeProvider.LocalTimeZone.

Standaard implementatie

.NET biedt een implementatie van TimeProvider via de eigenschap TimeProvider.System, met de volgende kenmerken:

Datum en tijd worden berekend met DateTimeOffset.UtcNow en TimeZoneInfo.Local.
Tijdstempels worden geleverd door System.Diagnostics.Stopwatch.
Timers worden geïmplementeerd via een interne klasse en weergegeven als System.Threading.ITimer.

In het volgende voorbeeld ziet u hoe u TimeProvider gebruikt om de huidige datum en tijd op te halen:

Console.WriteLine($"Local: {TimeProvider.System.GetLocalNow()}");
Console.WriteLine($"Utc:   {TimeProvider.System.GetUtcNow()}");

/* This example produces output similar to the following:
 *
 * Local: 12/5/2024 10:41:14 AM -08:00
 * Utc:   12/5/2024 6:41:14 PM +00:00
*/

Console.WriteLine($"Local: {TimeProvider.System.GetLocalNow()}")
Console.WriteLine($"Utc:   {TimeProvider.System.GetUtcNow()}")

' This example produces output similar to the following
'
' Local: 12/5/2024 10:41:14 AM -08:00
' Utc:   12/5/2024 6:41:14 PM +00:00

In het volgende voorbeeld ziet u hoe de verstreken tijd wordt vastgelegd met TimeProvider.GetTimestamp():

long stampStart = TimeProvider.System.GetTimestamp();
Console.WriteLine($"Starting timestamp: {stampStart}");

long stampEnd = TimeProvider.System.GetTimestamp();
Console.WriteLine($"Ending timestamp:   {stampEnd}");

Console.WriteLine($"Elapsed time: {TimeProvider.System.GetElapsedTime(stampStart, stampEnd)}");
Console.WriteLine($"Nanoseconds: {TimeProvider.System.GetElapsedTime(stampStart, stampEnd).TotalNanoseconds}"); 

/* This example produces output similar to the following:
 *
 * Starting timestamp: 55185546133
 * Ending timestamp:   55185549929
 * Elapsed time: 00:00:00.0003796
 * Nanoseconds: 379600
*/

Dim stampStart As Long = TimeProvider.System.GetTimestamp()
Console.WriteLine($"Starting timestamp: {stampStart}")

Dim stampEnd As Long = TimeProvider.System.GetTimestamp()
Console.WriteLine($"Ending timestamp:   {stampEnd}")

Console.WriteLine($"Elapsed time: {TimeProvider.System.GetElapsedTime(stampStart, stampEnd)}")
Console.WriteLine($"Nanoseconds: {TimeProvider.System.GetElapsedTime(stampStart, stampEnd).TotalNanoseconds}")

' This example produces output similar to the following:
'
' Starting timestamp: 55185546133
' Ending timestamp:   55185549929
' Elapsed time: 00:00:00.0003796
' Nanoseconds: 379600

FakeTimeProvider-implementatie

Het Microsoft.Extensions.TimeProvider.Testing NuGet-pakket biedt een besturingselementbare TimeProvider implementatie die is ontworpen voor eenheidstests.

In de volgende lijst worden enkele van de mogelijkheden van de FakeTimeProvider-klasse beschreven:

Stel een specifieke datum en tijd in.
De datum en tijd automatisch vooruitgaan met een opgegeven hoeveelheid wanneer de datum en tijd worden gelezen.
De datum en tijd handmatig vooruit instellen.

Aangepaste implementatie

Hoewel FakeTimeProvider de meeste scenario's moet behandelen waarvoor voorspelbaarheid met tijd is vereist, kunt u nog steeds uw eigen implementatie bieden. Maak een nieuwe klasse die is afgeleid van TimeProvider en overschrijf leden om te controleren hoe tijd wordt verstrekt. De volgende klasse biedt bijvoorbeeld slechts één datum, de datum van de maanlanding:

public class MoonLandingTimeProviderPST: TimeProvider
{
    // July 20, 1969, at 20:17:40 UTC
    private readonly DateTimeOffset _specificDateTime = new(1969, 7, 20, 20, 17, 40, TimeZoneInfo.Utc.BaseUtcOffset);

    public override DateTimeOffset GetUtcNow() => _specificDateTime;

    public override TimeZoneInfo LocalTimeZone => TimeZoneInfo.FindSystemTimeZoneById("PST");
}

Public Class MoonLandingTimeProviderPST
    Inherits TimeProvider

    'July 20, 1969, at 20:17:40 UTC
    Private ReadOnly _specificDateTime As New DateTimeOffset(1969, 7, 20, 20, 17, 40, TimeZoneInfo.Utc.BaseUtcOffset)

    Public Overrides Function GetUtcNow() As DateTimeOffset
        Return _specificDateTime
    End Function

    Public Overrides ReadOnly Property LocalTimeZone As TimeZoneInfo
        Get
            Return TimeZoneInfo.FindSystemTimeZoneById("PST")
        End Get
    End Property

End Class

Als code die deze klasse gebruikt, MoonLandingTimeProviderPST.GetUtcNowaanroept, wordt de datum van de maanlanding in UTC geretourneerd. Als MoonLandingTimeProviderPST.GetLocalNow wordt aangeroepen, past de basisklasse MoonLandingTimeProviderPST.LocalTimeZone toe op GetUtcNow en retourneert de maanlandingsdatum en -tijd in de PST-tijdzone.

Bekijk het volgende voorbeeld om de bruikbaarheid van de controletijd te demonstreren. Stel dat u een agenda-app schrijft die een begroeting naar de gebruiker verzendt wanneer de app elke dag voor het eerst wordt geopend. De app zegt een speciale begroeting wanneer er een gebeurtenis aan de huidige dag is gekoppeld, zoals het jubileum van de maanlanding.

public static class CalendarHelper
{
    static readonly DateTimeOffset MoonLandingDateTime = new(1969, 7, 20, 20, 17, 40, TimeZoneInfo.Utc.BaseUtcOffset);
    
    public static void SendGreeting(TimeProvider currentTime, string name)
    {
        DateTimeOffset localTime = currentTime.GetLocalNow();

        Console.WriteLine($"Good morning, {name}!");
        Console.WriteLine($"The date is {localTime.Date:d} and the day is {localTime.Date.DayOfWeek}.");

        if (localTime.Date.Month == MoonLandingDateTime.Date.Month
            && localTime.Date.Day == MoonLandingDateTime.Date.Day)
        {
            Console.WriteLine("Did you know that on this day in 1969 humans landed on the Moon?");
        }

        Console.WriteLine($"I hope you enjoy your day!");
    }
}

Public Module CalendarHelper

    ReadOnly MoonLandingDateTime As DateTimeOffset = #7/20/1969 20:17:40#

    Public Sub SendGreeting(currentTime As TimeProvider, name As String)

        Dim localTime As DateTimeOffset = currentTime.GetLocalNow()

        Console.WriteLine($"Good morning, {name}!")
        Console.WriteLine($"The date is {localTime.Date:d} and the day is {localTime.Date.DayOfWeek}.")

        If (localTime.Date.Month = MoonLandingDateTime.Date.Month _
            And localTime.Date.Day = MoonLandingDateTime.Date.Day) Then

            Console.WriteLine("Did you know that on this day in 1969 humans landed on the Moon?")
        End If

        Console.WriteLine($"I hope you enjoy your day!")

    End Sub

End Module

Mogelijk bent u geneigd om de vorige code te schrijven met DateTime of DateTimeOffset om de huidige datum en tijd op te halen in plaats van TimeProvider. Maar met eenheidstests is het moeilijk om rechtstreeks DateTime of DateTimeOffset te omzeilen. U moet de tests uitvoeren op de dag en maand van de maanlanding of de code verder abstraheren in kleinere maar testbare eenheden.

De normale werking van uw app gebruikt TimeProvider.System om de huidige datum en tijd op te halen:

CalendarHelper.SendGreeting(TimeProvider.System, "Eric Solomon");

/* This example produces output similar to the following:
 *
 * Good morning, Eric Solomon! 
 * The date is 12/5/2024 and the day is Thursday. 
 * I hope you enjoy your day! 
*/

CalendarHelper.SendGreeting(TimeProvider.System, "Eric Solomon")

' This example produces output similar to the following:
'
' Good morning, Eric Solomon! 
' The date is 12/5/2024 and the day is Thursday. 
' I hope you enjoy your day!

En eenheidstests kunnen worden geschreven om specifieke scenario's te testen, zoals het testen van het jubileum van de maanlanding:

CalendarHelper.SendGreeting(new MoonLandingTimeProviderPST(), "Eric Solomon");

/* This example produces output similar to the following:
 *
 * Good morning, Eric Solomon!
 * The date is 7/20/1969 and the day is Sunday.
 * Did you know that on this day in 1969 humans landed on the Moon?
 * I hope you enjoy your day!
*/

CalendarHelper.SendGreeting(New MoonLandingTimeProviderPST(), "Eric Solomon")

' This example produces output similar to the following:
'
' Good morning, Eric Solomon!
' The date is 7/20/1969 and the day is Sunday.
' Did you know that on this day in 1969 humans landed on the Moon?
' I hope you enjoy your day!

Gebruiken met .NET

Vanaf .NET 8 wordt de TimeProvider-klasse geleverd door de runtimebibliotheek. Oudere versies van .NET of bibliotheken die gericht zijn op .NET Standard 2.0, moeten verwijzen naar de Microsoft.Bcl.TimeProvider NuGet-pakket.

De volgende methoden met betrekking tot asynchrone programmering werken met TimeProvider:

Gebruiken met .NET Framework

TimeProvider wordt geïmplementeerd door het Microsoft.Bcl.TimeProvider NuGet-pakket.

Ondersteuning voor het werken met TimeProvider in asynchrone programmeerscenario's is toegevoegd via de volgende uitbreidingsmethoden:

Delen via