DateTimeOffsetConverter

Article
03/01/2023

The DateTimeOffsetConverter is a converter that allows users to convert a DateTimeOffset to a DateTime. Sometimes a DateTime value is stored with the offset on a backend to allow for storing the timezone in which a DateTime originated from. Controls like the Microsoft.Maui.Controls.DatePicker only work with DateTime. This converter can be used in those scenarios.

BaseConverter Properties

The following properties are implemented in the base class, public abstract class BaseConverter:

Property	Description
`DefaultConvertReturnValue`	Default value to return when `IValueConverter.Convert(object?, Type, object?, CultureInfo?)` throws an `Exception`. This value is used when CommunityToolkit.Maui.Options`.ShouldSuppressExceptionsInConverters` is set to `true`.
`DefaultConvertBackReturnValue`	Default value to return when `IValueConverter.ConvertBack(object?, Type, object?, CultureInfo?)` throws an `Exception`. This value is used when CommunityToolkit.Maui.Options`.ShouldSuppressExceptionsInConverters` is set to `true`.

ICommunityToolkitValueConverter Properties

The following properties are implemented in the public interface ICommunityToolkitValueConverter:

Property	Type	Description
`DefaultConvertReturnValue`	`object?`	Default value to return when `IValueConverter.Convert(object?, Type, object?, CultureInfo?)` throws an `Exception`. This value is used when CommunityToolkit.Maui.Options`.ShouldSuppressExceptionsInConverters` is set to `true`.
`DefaultConvertBackReturnValue`	`object?`	Default value to return when `IValueConverter.ConvertBack(object?, Type, object?, CultureInfo?)` throws an `Exception`. This value is used when CommunityToolkit.Maui.Options`.ShouldSuppressExceptionsInConverters` is set to `true`.

Syntax

XAML

Including the XAML namespace

In order to use the toolkit in XAML the following xmlns needs to be added into your page or view:

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Therefore the following:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Would be modified to include the xmlns as follows:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Using the DateTimeOffsetConverter

The DateTimeOffsetConverter can be used as follows in XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MyLittleApp.MainPage">
    <ContentPage.Resources>
         <ResourceDictionary>
             <toolkit:DateTimeOffsetConverter x:Key="DateTimeOffsetConverter" />
         </ResourceDictionary>
    </ContentPage.Resources>

    <VerticalStackLayout>
            <Label Text="The DatePicker below is bound to a Property of type DateTimeOffset."
                   Margin="16"
                   HorizontalOptions="Center"
                   FontAttributes="Bold" />

            <DatePicker Date="{Binding TheDate, Converter={StaticResource DateTimeOffsetConverter}}" 
                   Margin="16"
                   HorizontalOptions="Center" />

            <Label Text="{Binding TheDate}"
                   Margin="16"
                   HorizontalOptions="Center"
                   FontAttributes="Bold" />
        </VerticalStackLayout>
</ContentPage>

C#

The DateTimeOffsetConverter can be used as follows in C#:

class DateTimeOffsetConverterPage : ContentPage
{
    public DateTimeOffsetConverterPage()
    {
        var label = new Label();

        label.SetBinding(
            Label.TextProperty,
            new Binding(
                static (ViewModels vm) => vm.MyValue,
                converter: new DateTimeOffsetConverter()));

        Content = label;
    }
}

C# Markup

Our CommunityToolkit.Maui.Markup package provides a much more concise way to use this converter in C#.

using CommunityToolkit.Maui.Markup;

class DateTimeOffsetConverterPage : ContentPage
{
    public DateTimeOffsetConverterPage()
    {
        Content = new Label()
            .Bind(
                Label.TextProperty,
                static (ViewModel vm) => vm.MyValue,
                converter: new DateTimeOffsetConverter());
    }
}

Examples

You can find an example of this converter in action in the .NET MAUI Community Toolkit Sample Application.

API

You can find the source code for DateTimeOffsetConverter over on the .NET MAUI Community Toolkit GitHub repository.

Share via