C# Reference ยท Date, Time and Globalization
ISO 8601 weeks and the ISOWeek class
Reference for System.Globalization.ISOWeek in C#: week numbers, week-based years, weeks in a year, and converting a year, week and weekday back to a date.
ISOWeek is a static class in System.Globalization that implements the week numbering defined by ISO 8601. In that system a week always starts on Monday, and week 1 is the week that contains the first Thursday of the year. Equivalently, it is the week that contains 4 January.
The consequence is that the first days of January can belong to week 52 or 53 of the previous year, and the last days of December can belong to week 1 of the next year. Because of that, an ISO week number must always be paired with an ISO week-based year, and ISOWeek gives you both.
using System.Globalization; var d = new DateTime(2026, 1, 1); Console.WriteLine($"{ISOWeek.GetYear(d)}-W{ISOWeek.GetWeekOfYear(d):00}"); // 2026-W01
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public static class ISOWeek { public static int GetWeekOfYear(DateTime date); public static int GetYear(DateTime date); public static int GetWeeksInYear(int year); public static DateTime ToDateTime(int year, int week, DayOfWeek dayOfWeek); public static DateTime GetYearStart(int year); public static DateTime GetYearEnd(int year); }
| Member | Description |
|---|---|
GetWeekOfYear(date) |
ISO week number, 1 to 53, of the date. |
GetYear(date) |
ISO week-based year that the date's week belongs to. |
GetWeeksInYear(year) |
52 or 53, for a week-based year. |
ToDateTime(year, week, dayOfWeek) |
The date of that weekday in that week. |
GetYearStart(year) |
Monday of week 1 of the week-based year. |
GetYearEnd(year) |
Sunday of the last week of the week-based year. |
Returns: numbers or DateTime values with Kind Unspecified and the time at midnight.
Errors: ToDateTime throws ArgumentOutOfRangeException when the week is outside 1 to 53 or the year is outside 1 to 9999. A week 53 in a year that only has 52 weeks is not rejected: it rolls into week 1 of the next year (ToDateTime(2025, 53, DayOfWeek.Monday) is 2025-12-29, which is week 1 of 2026). GetWeeksInYear, GetYearStart and GetYearEnd throw for years outside 1 to 9999.
Usage notes
- Do not mix calendar years with ISO weeks. The label "2024-W01" for 30 December 2024 uses the week-based year 2025, not
date.Year. Always printISOWeek.GetYear(d)next to the week number. - Weeks start on Monday.
ISOWeekignores the current culture, so the result is the same everywhere. This differs fromCalendar.GetWeekOfYearcombined with aCalendarWeekRule, which depends on settings you pass in.Calendar.GetWeekOfYearwithCalendarWeekRule.FirstFourDayWeekandDayOfWeek.Mondaylooks similar, but it has no week-based year and can disagree with ISO near year boundaries, so useISOWeekfor ISO numbering. - A year has 53 weeks when 1 January falls on a Thursday, or on a Wednesday in a leap year. That is why 2026 has 53 weeks and 2025 has 52.
- The ISO week format
2026-W07-3(year, week, weekday 1 to 7 with Monday as 1) has no built-inToStringformat. Build it fromGetYear,GetWeekOfYearand a weekday number you compute yourself, where Sunday is 7 and not 0. - Group by week for reports with
GroupBy(d => (ISOWeek.GetYear(d), ISOWeek.GetWeekOfYear(d))), using the pair as the key. - Using
DateOnly: convert withdate.ToDateTime(TimeOnly.MinValue)before callingISOWeek, and withDateOnly.FromDateTime(...)on a result. - Added in .NET Core 3.0 (and .NET 5 and later), so it is available in all modern .NET versions.
Related
- DateTime
- DateOnly
- UTC vs. local time
- Tutorial: Dates and times