[Breaking change]: DateTimePicker's Text Property

[Epica3055]

Description

The Text property of DateTimePicker is empty before DateTimePicker's handle is created.

Version

• .NET 8.0

Previous behavior

After DateTimePicker was constructed, Text property was available. We didn't have to wait until the handle was created.

New behavior

Text property is an empty string until the handle is created, after the handle is created, Text is set to the current date as is displayed in the control.

Type of breaking change

• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

This behavior was introduced as a fix for issue 9232, to match narrator (screen reader) announcement to the display text. Fixed by pr 9253

The reason why issue 9232 occurred is that we accessed Text by

class DateTimePicker
{
...
    public override string Text
    {
        get => Value.ToString(CustomFormat);
...
}

If we hadn't set a CustomFormat, then there would be default CustomFormat. So there would be a disparity between the Text property and the displayed text.

So we changed the logic to

class DateTimePicker
{
...
    public override string Text
    {
        get => base.Text;
...
}

base.Text is identical with native Control text. So it doesn't matter if there is CustomFormat, the Text will be consistent
with what it looks only after the handle is created.

Recommended action

Since now if the Handle is not created then the Text will be a empty string. So we recommend you to access Text in later moment like:

public partial class Form1 : Form
{
    public Form1()
    {
        InitializeComponent();
        Shown += DateTimePicker_Shown;
    }

    private void DateTimePicker_Shown(object sender, EventArgs e)
    {
        this.dateTimePicker1.Text;
    }
}

Feature area

Windows Forms

---

Associated WorkItem - 263560

[gewarren]

@dreddy-work Do you want this documented as a breaking change? If so, the template is here: https://github.com/dotnet/docs/issues/new?assignees=gewarren&labels=breaking-change%2CPri1%2Cdoc-idea&projects=&template=breaking-change.yml&title=%5BBreaking+change%5D%3A+.

[merriemcgaw]

@Tanya-Solyanik will take a look and help with the breaking changes doc.

[adegeo]

@merriemcgaw what's the status of this issue?

[merriemcgaw]

@Tanya-Solyanik what are your thoughts? I don't recall this issue myself.

[Tanya-Solyanik]

@gewarren @merriemcgaw - we should document this as a breaking change.

@Epica3055 - please use the template mentioned above.

[Tanya-Solyanik]

@gewarren - Did we answer all questions for the breaking change?