Struct System.TimeSpan

Articolo
01/08/2024

Questo articolo fornisce osservazioni supplementari alla documentazione di riferimento per questa API.

Un TimeSpan oggetto rappresenta un intervallo di tempo (durata del tempo o tempo trascorso) misurato come numero positivo o negativo di giorni, ore, minuti, secondi e frazioni di secondo. La TimeSpan struttura può essere utilizzata anche per rappresentare l'ora del giorno, ma solo se l'ora non è correlata a una data specifica. In caso contrario, la DateTime struttura o DateTimeOffset deve essere utilizzata. Per altre informazioni sull'uso della TimeSpan struttura per riflettere l'ora del giorno, vedere Scelta tra DateTime, DateTimeOffset, TimeSpan e TimeZoneInfo.

Nota

Un TimeSpan valore rappresenta un intervallo di tempo e può essere espresso come un determinato numero di giorni, ore, minuti, secondi e millisecondi. Poiché rappresenta un intervallo generale senza riferimento a un determinato punto iniziale o finale, non può essere espresso in termini di anni e mesi, entrambi con un numero variabile di giorni. Differisce da un DateTime valore, che rappresenta una data e un'ora senza riferimento a un particolare fuso orario o a un DateTimeOffset valore, che rappresenta un momento specifico dell'ora.

L'unità di tempo più grande utilizzata dalla struttura per misurare la TimeSpan durata è un giorno. Gli intervalli di tempo vengono misurati in giorni per coerenza, perché il numero di giorni in unità di tempo maggiori, ad esempio mesi e anni, varia.

Il valore di un TimeSpan oggetto è il numero di tick uguali all'intervallo di tempo rappresentato. Un segno di graduazione è uguale a 100 nanosecondi o un dieci milionesimo di secondo. Il valore di un TimeSpan oggetto può variare da TimeSpan.MinValue a TimeSpan.MaxValue.

Creare un'istanza di un valore TimeSpan

È possibile creare un'istanza di un TimeSpan valore in diversi modi:

Chiamando il relativo costruttore implicito senza parametri. Verrà creato un oggetto il cui valore è TimeSpan.Zero, come illustrato nell'esempio seguente.

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".

Chiamando uno dei relativi costruttori espliciti. Nell'esempio seguente viene inizializzato un TimeSpan valore in un numero specificato di ore, minuti e secondi.

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".

Chiamando un metodo o eseguendo un'operazione che restituisce un TimeSpan valore. Ad esempio, è possibile creare un'istanza di un TimeSpan valore che rappresenta l'intervallo tra due valori di data e ora, come illustrato nell'esempio seguente.

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

È anche possibile inizializzare un TimeSpan oggetto in un valore zero time in questo modo, come illustrato nell'esempio seguente.

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 i valori vengono restituiti da operatori aritmetici e metodi delle DateTimestrutture , DateTimeOffsete TimeSpan .

Analizzando la rappresentazione di stringa di un TimeSpan valore. È possibile usare i Parse metodi e TryParse per convertire stringhe che contengono intervalli di tempo in TimeSpan valori. Nell'esempio seguente viene utilizzato il Parse metodo per convertire una matrice di stringhe in TimeSpan valori.

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'

Inoltre, è possibile definire il formato preciso della stringa di input da analizzare e convertire in un TimeSpan valore chiamando il ParseExact metodo o TryParseExact .

Eseguire operazioni sui valori TimeSpan

È possibile aggiungere e sottrarre durate temporali usando gli Addition operatori e Subtraction oppure chiamando i Add metodi e Subtract . È anche possibile confrontare due durate chiamando i Comparemetodi , CompareToe Equals . La TimeSpan struttura include anche i Duration metodi e Negate , che converte gli intervalli di tempo in valori positivi e negativi,

L'intervallo di TimeSpan valori è MinValue di MaxValue.

Formattare un valore TimeSpan

Un TimeSpan valore può essere rappresentato come [-]d.hh:mm:ss.ff, dove il segno meno facoltativo indica un intervallo di tempo negativo, il componente d è giorni, hh è ore misurate su un orologio di 24 ore, mm è minuti, ss è secondi e ff è frazione di un secondo. Ovvero, un intervallo di tempo è costituito da un numero positivo o negativo di giorni senza un'ora del giorno o un numero di giorni con un'ora del giorno o solo un'ora del giorno.

A partire da .NET Framework 4, la TimeSpan struttura supporta la formattazione sensibile alle impostazioni cultura tramite gli overload del relativo ToString metodo, che converte un TimeSpan valore nella relativa rappresentazione di stringa. Il metodo predefinito TimeSpan.ToString() restituisce un intervallo di tempo usando un formato invariante identico al valore restituito nelle versioni precedenti di .NET Framework. L'overload TimeSpan.ToString(String) consente di specificare una stringa di formato che definisce la rappresentazione di stringa dell'intervallo di tempo. L'overload TimeSpan.ToString(String, IFormatProvider) consente di specificare una stringa di formato e le impostazioni cultura le cui convenzioni di formattazione vengono usate per creare la rappresentazione di stringa dell'intervallo di tempo. TimeSpan supporta stringhe di formato standard e personalizzate. Per altre informazioni, vedere Stringhe di formato TimeSpan standard e stringhe di formato TimeSpan personalizzate. Tuttavia, solo le stringhe di formato standard sono sensibili alle impostazioni cultura.

Ripristinare la formattazione TimeSpan legacy

In alcuni casi, il codice che formatta TimeSpan correttamente i valori in .NET Framework 3.5 e versioni precedenti ha esito negativo in .NET Framework 4. Questo è più comune nel codice che chiama un <metodo di elemento TimeSpan_LegacyFormatMode> per formattare un TimeSpan valore con una stringa di formato. L'esempio seguente formatta correttamente un TimeSpan valore in .NET Framework 3.5 e versioni precedenti, ma genera un'eccezione in .NET Framework 4 e versioni successive. Si noti che tenta di formattare un TimeSpan valore usando un identificatore di formato non supportato, che viene ignorato in .NET Framework 3.5 e versioni precedenti.

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

Se non è possibile modificare il codice, è possibile ripristinare la formattazione legacy dei TimeSpan valori in uno dei modi seguenti:

Creando un file di configurazione contenente l'elemento <TimeSpan_LegacyFormatMode>. L'impostazione dell'attributo di enabled questo elemento per true ripristinare la formattazione legacy TimeSpan in base all'applicazione.

Impostando l'opzione di compatibilità "NetFx40_TimeSpanLegacyFormatMode" quando si crea un dominio applicazione. Ciò consente la formattazione legacy TimeSpan in base al dominio applicazione. Nell'esempio seguente viene creato un dominio applicazione che usa la formattazione legacy TimeSpan .

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

Quando il codice seguente viene eseguito nel nuovo dominio applicazione, viene ripristinato il comportamento di formattazione legacy TimeSpan .

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.

Struct System.TimeSpan

Creare un'istanza di un valore TimeSpan

Eseguire operazioni sui valori TimeSpan

Formattare un valore TimeSpan

Ripristinare la formattazione TimeSpan legacy

Commenti e suggerimenti

Risorse aggiuntive