Working with Weeks and DateOnly: Enhanced ISOWeek in .NET 10

Time handling in software has always been deceptively complex — week numbering, ISO compliance, leap years, and cultural variations make what seems simple far from trivial.
With .NET 10, the System.Globalization.ISOWeek class receives significant enhancements, bridging the gap between DateOnly, DateTime, and standardised week-based calculations.

Let’s explore how this improvement simplifies calendar-based operations, scheduling systems, and reporting utilities – all with predictable, ISO-8601-compliant week logic.

Why Weeks Matter More Than You Think

Many industries rely on ISO week numbers:

• Retail uses them for sales reporting and weekly KPIs.
• Manufacturing uses ISO weeks for production schedules.
• Finance often references fiscal calendars based on week numbers.

Before .NET 10, developers working with week-based data had to rely on either DateTime or manually calculate ISO weeks — both clunky and error-prone when working with modern types like DateOnly.

Now, ISOWeek has been upgraded to speak directly to DateOnly, bringing clarity and consistency.

The Problem Before .NET 10

Prior to these enhancements:

• ISOWeek worked only with DateTime.
• Developers had to convert between DateOnly and DateTime constantly.
• Week calculations involving time zones or calendar offsets could easily go wrong.

Example (pre-.NET 10):

var dateOnly = new DateOnly(2024, 12, 31);
var week = ISOWeek.GetWeekOfYear(dateOnly.ToDateTime(TimeOnly.MinValue)); // Awkward

This not only added verbosity but introduced potential for subtle bugs – especially when time-of-day conversions were accidentally localised.

The .NET 10 Solution: ISOWeek Meets DateOnly

Starting with .NET 10, ISOWeek now includes overloaded methods that work natively with DateOnly.
This makes week-based arithmetic direct, type-safe, and semantically clean.

var date = new DateOnly(2025, 1, 1);
int weekNumber = ISOWeek.GetWeekOfYear(date); // No conversions required

Additionally, you can move between week and date with minimal friction:

var mondayOfWeek = ISOWeek.ToDateOnly(2025, 1); // Returns DateOnly

This new API surface eliminates one of the last awkward gaps in the transition from DateTime to DateOnly.

Key Enhancements in ISOWeek for .NET 10

1. Full DateOnly Support

Every major method in ISOWeek now accepts or returns DateOnly.
That includes:

• GetWeekOfYear(DateOnly date)
• GetYear(DateOnly date)
• ToDateOnly(int year, int week)
• ToDateOnly(int year, int week, DayOfWeek dayOfWeek)

This means you can fully handle week-based operations without ever touching DateTime.

2. Bidirectional Conversion

You can now easily jump between ISO week and DateOnly without calendar math:

var weekStart = ISOWeek.ToDateOnly(2025, 20);
var weekEnd = weekStart.AddDays(6);

3. ISO-8601 Guaranteed Consistency

All operations are standardized to ISO 8601, which defines:

• Weeks start on Monday
• Week 1 is the one containing the first Thursday of the year

That means consistent week numbering across countries, time zones, and systems.

Real-World Example: Weekly Reporting System

Here’s a practical example using the new API:

public static class WeeklyReport
{
    public static (DateOnly Start, DateOnly End) GetWeekRange(DateOnly date)
    {
        var year = ISOWeek.GetYear(date);
        var week = ISOWeek.GetWeekOfYear(date);
        var start = ISOWeek.ToDateOnly(year, week, DayOfWeek.Monday);
        var end = start.AddDays(6);
        return (start, end);
    }
}

// Usage
var range = WeeklyReport.GetWeekRange(new DateOnly(2025, 5, 10));
Console.WriteLine($"Week Range: {range.Start} - {range.End}");

Output:

Week Range: 2025-05-05 - 2025-05-11

You can now produce accurate weekly summaries in your apps without manual date calculations.

Interop with DateOnly and Scheduling

The combination of DateOnly + ISOWeek is especially powerful for:

• Timesheet or roster apps
• Academic term scheduling
• Fiscal and retail calendars
• HR or attendance reporting

And because DateOnly represents dates without time zones, you avoid DST-related pitfalls.

Comparison: Old vs New

Future-Proof Design

The inclusion of DateOnly support within ISOWeek aligns with .NET’s broader move toward date/time clarity and immutability.
Expect future libraries (including scheduling, calendaring, and reporting frameworks) to adopt DateOnly as the standard for date-based logic.

Final Thoughts

The enhanced ISOWeek in .NET 10 might seem like a minor addition – but it’s a major step for developers working with week-based data.

It:

• Eliminates conversions and ambiguity,
• Guarantees ISO-8601 compliance, and
• Integrates naturally with the modern DateOnly ecosystem.

If you’re writing time-aware code — from payroll systems to retail analytics — it’s time to move your week logic to the new, cleaner API surface.