---
description: >-
  Data Management provides the properties needed to configure the core DateTime
  value, its time kind, and cultural context for humanizing date/time values.
---

# Data Management

## Overview

The Data Management feature of the `SiticoneHumanizerDateTime` control allows developers to set and retrieve the primary `DateTime` value for humanization, along with its associated time kind (local or UTC) and cultural formatting. This ensures that date/time values are correctly interpreted and displayed in a natural language format.

<table><thead><tr><th width="182">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Date</code></td><td>The core <code>DateTime</code> value to be humanized.</td></tr><tr><td><code>PreferredKind</code></td><td>Specifies whether to treat the <code>DateTime</code> as local or UTC.</td></tr><tr><td><code>Culture</code></td><td>Provides the cultural context for date and time formatting.</td></tr><tr><td><code>Humanize</code></td><td>A read-only property that returns the humanized string representation of the <code>DateTime</code> value.</td></tr></tbody></table>

### Key Points

<table><thead><tr><th width="182">Aspect</th><th>Detail</th></tr></thead><tbody><tr><td><code>Date</code></td><td>Holds the <code>DateTime</code> value to be converted into a natural language format.</td></tr><tr><td><code>PreferredKind</code></td><td>Determines if the <code>Date</code> property is treated as local time or UTC, affecting calculations.</td></tr><tr><td><code>Culture</code></td><td>Specifies the cultural context for formatting date/time outputs.</td></tr><tr><td><code>Humanize</code></td><td>Read-only property returning the humanized date/time representation.</td></tr></tbody></table>

### Best Practices

<table><thead><tr><th width="274">Practice</th><th>Recommendation</th></tr></thead><tbody><tr><td>Setting <code>Date</code></td><td>Always assign a valid <code>DateTime</code> value; avoid using default values like <code>DateTime.MinValue</code> unless intended.</td></tr><tr><td>Consistent <code>PreferredKind</code></td><td>Ensure <code>PreferredKind</code> aligns with your application’s handling of local or UTC times to prevent conversion issues.</td></tr><tr><td>Explicit <code>Culture</code> Assignment</td><td>Set the <code>Culture</code> property explicitly when targeting a specific regional format to avoid relying on defaults.</td></tr><tr><td>Read-only <code>Humanize</code> Usage</td><td>Use the <code>Humanize</code> property only for display or logging purposes and avoid modifying it programmatically.</td></tr></tbody></table>

### Common Pitfalls

<table><thead><tr><th width="322">Pitfall</th><th>Explanation</th></tr></thead><tbody><tr><td>Using Unspecified <code>DateTime</code></td><td>A <code>DateTime</code> with <code>DateTimeKind.Unspecified</code> may lead to unexpected results if not normalized properly.</td></tr><tr><td>Neglecting <code>PreferredKind</code> Setting</td><td>Failing to set <code>PreferredKind</code> correctly might result in discrepancies between local and UTC time displays.</td></tr><tr><td>Relying on Default <code>Culture</code></td><td>Not explicitly setting <code>Culture</code> can cause inconsistent formatting in multi-cultural or international applications.</td></tr></tbody></table>

### Usage Scenarios

<table><thead><tr><th width="254">Scenario</th><th>Details</th></tr></thead><tbody><tr><td>Simple Date Humanization</td><td>Set a <code>DateTime</code> value and retrieve the humanized string for display in a UI label or log.</td></tr><tr><td>Local vs. UTC Handling</td><td>Configure <code>PreferredKind</code> to manage how <code>Date</code> values are interpreted and ensure correct time zone conversion.</td></tr><tr><td>Localization</td><td>Use the <code>Culture</code> property to format the date in a region-specific manner.</td></tr></tbody></table>

### Real Life Usage Scenarios

<table><thead><tr><th width="320">Scenario</th><th>Details</th></tr></thead><tbody><tr><td>Global Event Logging</td><td>In logging systems where events occur across different time zones, set <code>PreferredKind</code> to manage local and UTC time properly.</td></tr><tr><td>User Interface for International Users</td><td>In applications with a global audience, explicitly set <code>Culture</code> to present dates in the user's regional format.</td></tr><tr><td>Reporting and Analytics</td><td>Use the <code>Humanize</code> property to provide natural language summaries (e.g., "3 hours ago") for time-based analytics.</td></tr></tbody></table>

### Troubleshooting Tips

| Issue                                       | Solution                                                                                                                         |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Incorrect Humanized Output                  | Verify that the `Date`, `PreferredKind`, and `Culture` properties are set correctly and consistently throughout the application. |
| Unexpected Results with Extreme Date Values | Ensure that special cases like `DateTime.MinValue` or `DateTime.MaxValue` are handled as per application requirements.           |
| Inconsistent Formatting                     | Check that the `Culture` property is explicitly set if the output formatting does not match the expected regional standards.     |

### Code Samples and Integration Examples

#### Basic Usage Example

```csharp
using System;
using System.Globalization;
using SiticoneNetFrameworkUI;

namespace DemoApp
{
    public class Demo
    {
        public static void Main()
        {
            // Create an instance of the SiticoneHumanizerDateTime control
            SiticoneHumanizerDateTime humanizer = new SiticoneHumanizerDateTime();

            // Set the primary date to a specific time (5 hours ago)
            humanizer.Date = DateTime.Now.AddHours(-5);

            // Define how the DateTime value should be interpreted (local time)
            humanizer.PreferredKind = DateTimeKind.Local;

            // Set the cultural context explicitly for US English formatting
            humanizer.Culture = new CultureInfo("en-US");

            // Retrieve the humanized output (e.g., "5 hours ago")
            string humanizedOutput = humanizer.Humanize;
            Console.WriteLine("Humanized Date: " + humanizedOutput);
        }
    }
}
```

#### Localization and Time Zone Handling

```csharp
using System;
using System.Globalization;
using SiticoneNetFrameworkUI;

namespace InternationalDemo
{
    public class LocalizationDemo
    {
        public static void Main()
        {
            // Initialize the humanizer control
            SiticoneHumanizerDateTime humanizer = new SiticoneHumanizerDateTime();

            // Assign a specific DateTime value
            humanizer.Date = new DateTime(2025, 12, 31, 23, 59, 59);

            // Set the preferred time kind to UTC
            humanizer.PreferredKind = DateTimeKind.Utc;

            // Change culture to French (France) for localization
            humanizer.Culture = new CultureInfo("fr-FR");

            // Output the humanized date string
            Console.WriteLine("Date humanisé: " + humanizer.Humanize);
        }
    }
}
```

### Review

<table><thead><tr><th width="150">Aspect</th><th>Comment</th></tr></thead><tbody><tr><td>Functionality</td><td>The Data Management feature offers a simple yet powerful way to configure the input <code>DateTime</code> and its associated context.</td></tr><tr><td>Integration</td><td>Integrates seamlessly with .NET applications by leveraging standard <code>DateTime</code> and <code>CultureInfo</code> constructs.</td></tr><tr><td>Localization</td><td>Provides flexibility through <code>PreferredKind</code> and <code>Culture</code> properties for accurate and culturally relevant date display.</td></tr></tbody></table>

### Summary

<table><thead><tr><th width="225">Summary Aspect</th><th>Description</th></tr></thead><tbody><tr><td>Core Date Management</td><td>Manages the central <code>DateTime</code> value with properties for time zone and cultural context.</td></tr><tr><td>Flexibility</td><td><code>PreferredKind</code> and <code>Culture</code> ensure that the <code>DateTime</code> is interpreted and formatted correctly based on application needs.</td></tr><tr><td>Ease of Use</td><td>The read-only <code>Humanize</code> property offers an immediate natural language representation of the date, simplifying integration.</td></tr></tbody></table>

### Frequently Asked Questions (FAQ)

| Question                                    | Answer                                                                                                                         |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| What happens if `Culture` is not set?       | The control defaults to `CultureInfo.CurrentCulture`, which might not match the intended locale in international applications. |
| Can `DateTime.MinValue` be used for `Date`? | While it is allowed, using extreme values may trigger special handling in the humanization logic.                              |
| How does `PreferredKind` affect output?     | It ensures that date/time calculations are consistent with either local time or UTC, depending on your setting.                |

### Tips for Developers

<table><thead><tr><th width="214">Tip</th><th>Recommendation</th></tr></thead><tbody><tr><td>Validate <code>Date</code> Input</td><td>Always validate that the <code>Date</code> property receives a proper <code>DateTime</code> value to avoid unintentional special case handling.</td></tr><tr><td>Consistent Application Settings</td><td>Use a central configuration for <code>Culture</code> and <code>PreferredKind</code> to maintain consistency across your application.</td></tr><tr><td>Testing</td><td>Test with various <code>DateTime</code> values, including edge cases like <code>DateTime.MinValue</code> and <code>DateTime.MaxValue</code>, to ensure robust output.</td></tr></tbody></table>

By following this documentation for Data Management, developers can integrate the `SiticoneHumanizerDateTime` control efficiently, ensuring that date/time values are displayed accurately and naturally within their .NET WinForms applications.
