System.TimeSpan-Struktur

Artikel
01/11/2024

Dieser Artikel enthält ergänzende Hinweise zur Referenzdokumentation für diese API.

Ein TimeSpan Objekt stellt ein Zeitintervall (Dauer der Zeit oder verstrichene Zeit) dar, das als positive oder negative Anzahl von Tagen, Stunden, Minuten, Sekunden und Bruchteilen einer Sekunde gemessen wird. Die TimeSpan Struktur kann auch verwendet werden, um die Tageszeit darzustellen, aber nur, wenn die Uhrzeit nicht mit einem bestimmten Datum verknüpft ist. Andernfalls sollte stattdessen die DateTime DateTimeOffset Struktur verwendet werden. (Weitere Informationen zur Verwendung der TimeSpan Struktur, um die Tageszeit widerzuspiegeln, finden Sie unter "Auswählen zwischen DateTime", "DateTimeOffset", "TimeSpan" und "TimeZoneInfo".)

Hinweis

Ein TimeSpan Wert stellt ein Zeitintervall dar und kann als bestimmte Anzahl von Tagen, Stunden, Minuten, Sekunden und Millisekunden ausgedrückt werden. Da es ein allgemeines Intervall ohne Bezug auf einen bestimmten Anfangs- oder Endpunkt darstellt, kann es nicht in Bezug auf Jahre und Monate ausgedrückt werden, die beide eine variable Anzahl von Tagen aufweisen. Er unterscheidet sich von einem DateTime Wert, der ein Datum und eine Uhrzeit ohne Bezug auf eine bestimmte Zeitzone oder einen DateTimeOffset Wert darstellt, der einen bestimmten Zeitmoment darstellt.

Die größte Zeiteinheit, die die Struktur zum Messen der TimeSpan Dauer verwendet, ist ein Tag. Zeitintervalle werden in Tagen für die Konsistenz gemessen, da die Anzahl der Tage in größeren Zeiteinheiten, z. B. Monate und Jahre, unterschiedlich ist.

Der Wert eines TimeSpan Objekts ist die Anzahl der Teilstriche, die dem dargestellten Zeitintervall entsprechen. Ein Teilstrich ist gleich 100 Nanosekunden oder ein Zehntel einer Sekunde. Der Wert eines TimeSpan Objekts kann von TimeSpan.MinValue bis zu TimeSpan.MaxValue.

Instanziieren eines TimeSpan-Werts

Sie können einen TimeSpan Wert auf verschiedene Arten instanziieren:

Durch Aufrufen des impliziten parameterlosen Konstruktors. Dadurch wird ein Objekt erstellt, dessen Wert wie im folgenden Beispiel dargestellt ist TimeSpan.Zero.

TimeSpan interval = new TimeSpan();
Console.WriteLine(interval.Equals(TimeSpan.Zero));    // Displays "True".

let interval = TimeSpan()
printfn $"{interval.Equals TimeSpan.Zero}"    // Displays "True".

Dim interval As New TimeSpan()
Console.WriteLine(interval.Equals(TimeSpan.Zero))     ' Displays "True".

Durch Aufrufen eines seiner expliziten Konstruktoren. Im folgenden Beispiel wird ein TimeSpan Wert auf eine angegebene Anzahl von Stunden, Minuten und Sekunden initialisiert.

TimeSpan interval = new TimeSpan(2, 14, 18);
Console.WriteLine(interval.ToString());              

// Displays "02:14:18".

let interval = TimeSpan(2, 14, 18)
printfn $"{interval}"              

// Displays "02:14:18".

Dim interval As New TimeSpan(2, 14, 18)
Console.WriteLine(interval.ToString())                ' Displays "02:14:18".

Durch Aufrufen einer Methode oder Ausführen eines Vorgangs, der einen TimeSpan Wert zurückgibt. Sie können beispielsweise einen TimeSpan Wert instanziieren, der das Intervall zwischen zwei Datums- und Uhrzeitwerten darstellt, wie im folgenden Beispiel gezeigt.

DateTime departure = new DateTime(2010, 6, 12, 18, 32, 0);
DateTime arrival = new DateTime(2010, 6, 13, 22, 47, 0);
TimeSpan travelTime = arrival - departure;  
Console.WriteLine("{0} - {1} = {2}", arrival, departure, travelTime);      

// The example displays the following output:
//       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

let departure = DateTime(2010, 6, 12, 18, 32, 0)
let arrival = DateTime(2010, 6, 13, 22, 47, 0)
let travelTime = arrival - departure  
printfn $"{arrival} - {departure} = {travelTime}"

// The example displays the following output:
//       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

Dim departure As DateTime = #06/12/2010 6:32PM#
Dim arrival As DateTime = #06/13/2010 10:47PM#
Dim travelTime As TimeSpan = arrival - departure
Console.WriteLine("{0} - {1} = {2}", arrival, departure, travelTime)
' The example displays the following output:
'       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

Sie können ein TimeSpan Objekt auch auf diese Weise auf einen Nullzeitwert initialisieren, wie im folgenden Beispiel gezeigt.

Random rnd = new Random();

TimeSpan timeSpent = TimeSpan.Zero;

timeSpent += GetTimeBeforeLunch();
timeSpent += GetTimeAfterLunch();

Console.WriteLine("Total time: {0}", timeSpent);

TimeSpan GetTimeBeforeLunch()
{
    return new TimeSpan(rnd.Next(3, 6), 0, 0);
}

TimeSpan GetTimeAfterLunch()
{
    return new TimeSpan(rnd.Next(3, 6), 0, 0);
}

// The example displays output like the following:
//        Total time: 08:00:00

open System

let rnd = Random()

let getTimeBeforeLunch () =
    TimeSpan(rnd.Next(3, 6), 0, 0)

let getTimeAfterLunch() =
    TimeSpan(rnd.Next(3, 6), 0, 0)

do
    let timeSpent = TimeSpan.Zero

    let timeSpent = timeSpent + getTimeBeforeLunch ()
    let timeSpent = timeSpent + getTimeAfterLunch ()

    printfn $"Total time: {timeSpent}"


// The example displays output like the following:
//        Total time: 08:00:00

Module Example
   Dim rnd As New Random()
   
   Public Sub Main()
      Dim timeSpent As TimeSpan = TimeSpan.Zero

      timeSpent += GetTimeBeforeLunch()
      timeSpent += GetTimeAfterLunch()

      Console.WriteLine("Total time: {0}", timeSpent)
   End Sub
   
   Private Function GetTimeBeforeLunch() As TimeSpan
      Return New TimeSpan(rnd.Next(3, 6), 0, 0)
   End Function
   
   Private Function GetTimeAfterLunch() As TimeSpan
      Return New TimeSpan(rnd.Next(3, 6), 0, 0)
   End Function
End Module
' The example displays output like the following:
'       Total time: 08:00:00

TimeSpan Werte werden von arithmetischen Operatoren und Methoden der DateTime, DateTimeOffsetund TimeSpan Strukturen zurückgegeben.

Durch Analysieren der Zeichenfolgendarstellung eines TimeSpan Werts. Mit den Parse Methoden können TryParse Sie Zeichenfolgen konvertieren, die Zeitintervalle in TimeSpan Werte enthalten. Im folgenden Beispiel wird die Parse Methode verwendet, um ein Array von Zeichenfolgen in Werte zu TimeSpan konvertieren.

string[] values = { "12", "31.", "5.8:32:16", "12:12:15.95", ".12"};
foreach (string value in values)
{
   try {
      TimeSpan ts = TimeSpan.Parse(value);
      Console.WriteLine("'{0}' --> {1}", value, ts);
   }
   catch (FormatException) {
      Console.WriteLine("Unable to parse '{0}'", value);
   }
   catch (OverflowException) {
      Console.WriteLine("'{0}' is outside the range of a TimeSpan.", value);
   }   
}

// The example displays the following output:
//       '12' --> 12.00:00:00
//       Unable to parse '31.'
//       '5.8:32:16' --> 5.08:32:16
//       '12:12:15.95' --> 12:12:15.9500000
//       Unable to parse '.12'

let values = [| "12"; "31."; "5.8:32:16"; "12:12:15.95"; ".12" |]
for value in values do
    try
        let ts = TimeSpan.Parse value
        printfn $"'{value}' --> {ts}"
    with 
    | :? FormatException ->
        printfn $"Unable to parse '{value}'"
    | :? OverflowException ->
        printfn $"'{value}' is outside the range of a TimeSpan."

// The example displays the following output:
//       '12' --> 12.00:00:00
//       Unable to parse '31.'
//       '5.8:32:16' --> 5.08:32:16
//       '12:12:15.95' --> 12:12:15.9500000
//       Unable to parse '.12'

Dim values() As String = {"12", "31.", "5.8:32:16", "12:12:15.95", ".12"}
For Each value As String In values
    Try
        Dim ts As TimeSpan = TimeSpan.Parse(value)
        Console.WriteLine("'{0}' --> {1}", value, ts)
    Catch e As FormatException
        Console.WriteLine("Unable to parse '{0}'", value)
    Catch e As OverflowException
        Console.WriteLine("'{0}' is outside the range of a TimeSpan.", value)
    End Try
Next
' The example displays the following output:
'       '12' --> 12.00:00:00
'       Unable to parse '31.'
'       '5.8:32:16' --> 5.08:32:16
'       '12:12:15.95' --> 12:12:15.9500000
'       Unable to parse '.12'

Darüber hinaus können Sie das genaue Format der Eingabezeichenfolge definieren, die analysiert und in einen TimeSpan Wert konvertiert werden soll, indem Sie die ParseExact Methode aufrufen TryParseExact .

Ausführen von Vorgängen für TimeSpan-Werte

Sie können Zeitdauern hinzufügen und subtrahieren, entweder mithilfe der Addition Operatoren Subtraction oder durch Aufrufen der Add Methoden Subtract . Sie können auch zwei Zeitdauern vergleichen, indem Sie die CompareMethoden und Equals CompareToMethoden aufrufen. Die TimeSpan Struktur enthält auch die Duration Und Negate Methoden, mit denen Zeitintervalle in positive und negative Werte konvertiert werden,

Der Wertebereich TimeSpan besteht MinValue darin, MaxValue.

Formatieren eines TimeSpan-Werts

Ein TimeSpan Wert kann als [-]d dargestellt werden.hh:mm:ss.ff, wobei das optionale Minuszeichen ein negatives Zeitintervall angibt, die d-Komponente Tage, hh ist Stunden wie in einer 24-Stunden-Uhr gemessen, mm ist Minuten, ss ist Sekunden, und ff ist Brüche einer Sekunde. Das heißt, ein Zeitintervall besteht aus einer positiven oder negativen Anzahl von Tagen ohne Tageszeit oder einer Anzahl von Tagen mit einer Tageszeit oder nur einer Tageszeit.

Ab .NET Framework 4 unterstützt die TimeSpan Struktur kultursensitive Formatierungen über die Überladungen der ToString Methode, die einen TimeSpan Wert in die Zeichenfolgendarstellung konvertiert. Die Standardmethode TimeSpan.ToString() gibt ein Zeitintervall zurück, indem ein invariantes Format verwendet wird, das mit dem Rückgabewert in früheren Versionen von .NET Framework identisch ist. Mit der TimeSpan.ToString(String) Überladung können Sie eine Formatzeichenfolge angeben, die die Zeichenfolgendarstellung des Zeitintervalls definiert. Mit der TimeSpan.ToString(String, IFormatProvider) Überladung können Sie eine Formatzeichenfolge und die Kultur angeben, deren Formatierungskonventionen zum Erstellen der Zeichenfolgendarstellung des Zeitintervalls verwendet werden. TimeSpan unterstützt sowohl Standard- als auch benutzerdefinierte Formatzeichenfolgen. (Weitere Informationen finden Sie unter Standardmäßige TimeSpan-Formatzeichenfolgen und benutzerdefinierte TimeSpan-Formatzeichenfolgen.) Allerdings sind nur Standardformatzeichenfolgen kulturempfindlich.

Wiederherstellen der älteren TimeSpan-Formatierung

In einigen Fällen schlägt Code, der Werte in .NET Framework 3.5 und früheren Versionen erfolgreich formatiert TimeSpan , in .NET Framework 4 fehl. Dies ist am häufigsten in Code, der eine <TimeSpan_LegacyFormatMode> Elementmethode aufruft, um einen TimeSpan Wert mit einer Formatzeichenfolge zu formatieren. Das folgende Beispiel formatiert erfolgreich einen TimeSpan Wert in .NET Framework 3.5 und früheren Versionen, löst jedoch eine Ausnahme in .NET Framework 4 und höheren Versionen aus. Beachten Sie, dass versucht wird, einen TimeSpan Wert mithilfe eines nicht unterstützten Formatbezeichners zu formatieren, der in .NET Framework 3.5 und früheren Versionen ignoriert wird.

ShowFormattingCode();
// Output from .NET Framework 3.5 and earlier versions:
//       12:30:45
// Output from .NET Framework 4:
//       Invalid Format    

Console.WriteLine("---");

ShowParsingCode();
// Output:
//       000000006 --> 6.00:00:00

void ShowFormattingCode()
{
    TimeSpan interval = new TimeSpan(12, 30, 45);
    string output;
    try
    {
        output = String.Format("{0:r}", interval);
    }
    catch (FormatException)
    {
        output = "Invalid Format";
    }
    Console.WriteLine(output);
}

void ShowParsingCode()
{
    string value = "000000006";
    try
    {
        TimeSpan interval = TimeSpan.Parse(value);
        Console.WriteLine("{0} --> {1}", value, interval);
    }
    catch (FormatException)
    {
        Console.WriteLine("{0}: Bad Format", value);
    }
    catch (OverflowException)
    {
        Console.WriteLine("{0}: Overflow", value);
    }
}

let showFormattingCode () =
    let interval = TimeSpan(12, 30, 45)
    try
        $"{interval:r}"
    with :? FormatException ->
        "Invalid Format"
    |> printfn "%s"

let showParsingCode () =
    let value = "000000006"
    try
        let interval = TimeSpan.Parse value
        printfn $"{value} --> {interval}"
    with
    | :? FormatException ->
        printfn $"{value}: Bad Format"
    | :? OverflowException ->
        printfn $"{value}: Overflow"

showFormattingCode ()
// Output from .NET Framework 3.5 and earlier versions:
//       12:30:45
// Output from .NET Framework 4:
//       Invalid Format    

printfn "---"

showParsingCode ()
// Output:
//       000000006 --> 6.00:00:00

Dim interval As New TimeSpan(12, 30, 45)
Dim output As String
Try
    output = String.Format("{0:r}", interval)
Catch e As FormatException
    output = "Invalid Format"
End Try
Console.WriteLine(output)
' Output from .NET Framework 3.5 and earlier versions:
'       12:30:45
' Output from .NET Framework 4:
'       Invalid Format

Wenn Sie den Code nicht ändern können, können Sie die ältere Formatierung von TimeSpan Werten auf eine der folgenden Arten wiederherstellen:

Durch Erstellen einer Konfigurationsdatei, die das <TimeSpan_LegacyFormatMode-Element> enthält. Wenn Sie das enabled Attribut dieses Elements so festlegen, dass true ältere Formatierungen TimeSpan pro Anwendung wiederhergestellt werden.

Indem Sie den Kompatibilitätsschalter "NetFx40_TimeSpanLegacyFormatMode" festlegen, wenn Sie eine Anwendung erstellen Standard. Dies ermöglicht die Legacyformatierung pro Anwendung Standard.This enables legacy TimeSpan formatting on a pro application-do Standard basis. Im folgenden Beispiel wird eine Anwendung erstellt Standard die ältere TimeSpan Formatierung verwendet.

using System;

public class Example2
{
    public static void Main()
    {
        AppDomainSetup appSetup = new AppDomainSetup();
        appSetup.SetCompatibilitySwitches(new string[] { "NetFx40_TimeSpanLegacyFormatMode" });
        AppDomain legacyDomain = AppDomain.CreateDomain("legacyDomain",
                                                        null, appSetup);
        legacyDomain.ExecuteAssembly("ShowTimeSpan.exe");
    }
}

open System

let appSetup = AppDomainSetup()
appSetup.SetCompatibilitySwitches [| "NetFx40_TimeSpanLegacyFormatMode" |]
let legacyDomain = AppDomain.CreateDomain("legacyDomain", null, appSetup)
legacyDomain.ExecuteAssembly "ShowTimeSpan.exe" |> ignore

Module Example3
    Public Sub Main()
        Dim appSetup As New AppDomainSetup()
        appSetup.SetCompatibilitySwitches({"NetFx40_TimeSpanLegacyFormatMode"})
        Dim legacyDomain As AppDomain = AppDomain.CreateDomain("legacyDomain",
                                                             Nothing, appSetup)
        legacyDomain.ExecuteAssembly("ShowTimeSpan.exe")
    End Sub
End Module

Wenn der folgende Code in der neuen Anwendung ausgeführt wird Standard rückgängig machen es auf das Verhalten der älteren TimeSpan Formatierung.

using System;

public class Example3
{
   public static void Main()
   {
      TimeSpan interval = DateTime.Now - DateTime.Now.Date;
      string msg = String.Format("Elapsed Time Today: {0:d} hours.",
                                 interval);
      Console.WriteLine(msg);
   }
}
// The example displays the following output:
//       Elapsed Time Today: 01:40:52.2524662 hours.

open System

let interval = DateTime.Now - DateTime.Now.Date
printfn $"Elapsed Time Today: {interval:d} hours."
// The example displays the following output:
//       Elapsed Time Today: 01:40:52.2524662 hours.

Module Example4
    Public Sub Main()
        Dim interval As TimeSpan = Date.Now - Date.Now.Date
        Dim msg As String = String.Format("Elapsed Time Today: {0:d} hours.",
                                         interval)
        Console.WriteLine(msg)
    End Sub
End Module
' The example displays output like the following:
'       Elapsed Time Today: 01:40:52.2524662 hours.

Freigeben über

System.TimeSpan-Struktur

Instanziieren eines TimeSpan-Werts

Ausführen von Vorgängen für TimeSpan-Werte

Formatieren eines TimeSpan-Werts

Wiederherstellen der älteren TimeSpan-Formatierung

Zusätzliche Ressourcen