dotnet / dotnet/dotnet-api-docs

DateTime.MinValue has very odd interactions with Value and unclear, undocumented requirements

Aperta
#4,435 4 commenti 0 reazioni 0 assegnatari Vedi su GitHub
area-WinForms Pri3 untriaged
Lingua principale
C#
Stelle
949
Fork
1.7k
Merge medio
2g 19h
PR unite (30g)
52

Descrizione

Someone asked a question on reddit about some odd behavior they were seeing when manipulating the `MinDate` property of a `DateTimePicker`. They set `MinDate` to `DateTime.MinValue`, then later tried to set `Value` to the same value. However, they got an exception informing them that the value was out of range. When I was poking at it, I managed to get an error with a different date that told me `MinDate` must be set to a date later than 1753.

When I examined the code for `DateTimePicker` it became clear. There is some validation logic that throws if the `MinDate` value is earlier than 1753 because of "problems with that year". (I think the author got confused, 1582 is the 'strange' year in Gregorian.) So why doesn't it throw when I set it the first time? Well, the first thing it does is compare the current backing field to the new value and it bypasses all logic if they are the same. The control itself initializes the backing field to `DateTime.MinValue`. So even though that is an *invalid* value for the property, it is valid *as long as the property has not yet been changed*. But bad things happen if you later try to set `Value` to `DateTime.MinValue`: the getter for `MinDate` defers to an internal method that returns a date in 1753.

This entails multiple documentation changes:

* `DateTimePicker.MinDate` should document that it throws an exception if you try to set it to a date before 1753.
* It casually mentions this date as the default, but does not clarify dates earlier than this are invalid.
* `DateTimePicker.MinDate` should document it actually won't throw that exception if you try to set it to `DateTime.MinValue` if and only if you haven't set it to another value. (Or the WinForms team should correct this error, but it's probably set in stone 'for historic reasons' at this point.)
* `DateTimePicker.Value` should document that it will throw if you try to set a date before 1753 even if, because of the last point, you've set `DateTimePicker.MinDate` to `DateTime.MinValue`.
* It currently indicates it throws if the value you set is less than `DateTimePicker.MinDate`, but since you can set `DateTimePicker.MinDate` to an invalid value that isn't quite true. (Or the WinForms team could correct this error.)
* It seems like the field `DateTimePicker.MinDateTime` is the appropriate minimum value for these fields, but I've been using .NET since 2003 and today is the first time I've noticed it, it's unmentioned in any of the above documentation despite being the basis for coercion and validation.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Inizia con le voci di riferimento dell'API per DateTimePicker.MinDate, DateTimePicker.Value e DateTimePicker.MinDateTime, quindi confronta le relative osservazioni attuali e la documentazione delle eccezioni con il comportamento descritto nell'issue. Il lavoro è completato quando i vincoli documentati sulla data minima, il comportamento eccezionale di DateTime.MinValue e il ruolo di MinDateTime sono accurati e coerenti.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
csharp
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
38/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.