Introduction

TimeSpan.Milliseconds and TimeSpan.TotalMilliseconds look similar, but they answer different questions. One gives you only the millisecond component of the interval, while the other gives you the full duration converted to milliseconds.

The Key Difference

Use Milliseconds when you want the leftover millisecond part after seconds have been removed. Use TotalMilliseconds when you want the entire duration expressed as milliseconds.

Consider this example:

1using System;
2
3var span = new TimeSpan(0, 0, 1, 2, 345);
4
5Console.WriteLine(span.Milliseconds);
6Console.WriteLine(span.TotalMilliseconds);

Output:

345
62345

The interval is 1 minute, 2 seconds, and 345 milliseconds.

• 'Milliseconds returns only 345'
• 'TotalMilliseconds returns the whole interval as 62345'

That is the difference in one line.

Think In Components Versus Totals

TimeSpan exposes both component properties and total properties:

• 'Days, Hours, Minutes, Seconds, Milliseconds'
• 'TotalDays, TotalHours, TotalMinutes, TotalSeconds, TotalMilliseconds'

The component properties are like reading a formatted clock. The total properties are like converting the entire interval into one unit.

This example makes the distinction clearer:

1var span = TimeSpan.FromMilliseconds(3723004);
2
3Console.WriteLine($"Days: {span.Days}");
4Console.WriteLine($"Hours: {span.Hours}");
5Console.WriteLine($"Minutes: {span.Minutes}");
6Console.WriteLine($"Seconds: {span.Seconds}");
7Console.WriteLine($"Milliseconds: {span.Milliseconds}");
8Console.WriteLine($"TotalMilliseconds: {span.TotalMilliseconds}");

Even though the total duration is more than three million milliseconds, Milliseconds still reports only the final component that remains after larger units are split out.

When To Use Milliseconds

Use Milliseconds when you are formatting or displaying the component pieces of a duration.

For example:

var span = TimeSpan.FromSeconds(3.456);
Console.WriteLine($"{span.Seconds}s {span.Milliseconds}ms");

That is useful for log messages, stopwatch-style displays, or any situation where you want a human-readable breakdown.

It is not a good choice when you are calculating delays, thresholds, or elapsed-time comparisons, because it discards all larger units.

When To Use TotalMilliseconds

Use TotalMilliseconds when you need the real duration in milliseconds for math or comparisons.

1var timeout = TimeSpan.FromSeconds(2.5);
2
3if (timeout.TotalMilliseconds > 2000)
4{
5    Console.WriteLine("Timeout is longer than two seconds.");
6}

This is the right property for:

• timing logic
• retry delays
• statistics and metrics
• converting a TimeSpan into another numeric unit

TotalMilliseconds is a double, so it can represent fractional milliseconds as well.

Negative TimeSpans

The distinction matters with negative values too:

1var span = TimeSpan.FromMilliseconds(-1500);
2
3Console.WriteLine(span.Milliseconds);
4Console.WriteLine(span.TotalMilliseconds);

TotalMilliseconds gives the whole negative duration. Milliseconds still reflects only the component portion, which can be surprising if you expected a complete converted value.

That is another reason to use totals for calculations and component properties for formatting.

A Common Bug

A classic mistake is writing code like this:

1if (elapsed.Milliseconds > 500)
2{
3    Console.WriteLine("Operation took more than half a second.");
4}

This is wrong. If elapsed is 2.100 seconds, Milliseconds is only 100, so the check fails even though the full interval is greater than 500 milliseconds.

The correct version is:

1if (elapsed.TotalMilliseconds > 500)
2{
3    Console.WriteLine("Operation took more than half a second.");
4}

Common Pitfalls

• Using Milliseconds for comparisons or timeout logic.
• Forgetting that Milliseconds is only the component portion, not the full duration.
• Ignoring that TotalMilliseconds returns a double, which may need rounding when converted to an integer.
• Assuming component properties behave like totals for negative intervals.
• Mixing display logic and calculation logic in the same code path.

Summary

• 'Milliseconds is the millisecond component only.'
• 'TotalMilliseconds is the entire TimeSpan converted to milliseconds.'
• Use component properties for formatting.
• Use total properties for math, comparisons, and timing logic.
• If you need the real elapsed duration, TotalMilliseconds is almost always the correct property.