ITimeZoneIDConverter Interface

The vCard 4.0 standard recommends specifying time zones as IANA time zone names. - Older standards (vCard 2.1, vCard 3.0), however, prefer UTC offsets.

It is possible to convert IANA time zone names to UTC offsets, but it's not possible to convert UTC offsets to IANA time zone names because there is no unique assignment. Therefore it's recommended to initialize TimeZoneID objects with IANA time zone names and then to convert these to UTC offsets using an implementation of ITimeZoneIDConverter when serializing a vCard 2.1 or a vCard 3.0.

Since .NET cannot do the conversion itself, this interface enables a 3rd-party library to be integrated. (Since .NET 6.0 exists a .NET solution with the ICU library but this needs a separate dependency or additional configuration.)

Example implementation for ITimeZoneIDConverter:

using FolkerKinzel.VCards;

namespace Examples;

/// <summary>
/// Example implementation of <see cref="ITimeZoneIDConverter"/> to convert IANA time zone 
/// names into UTC offsets in order to be compatible to older vCard clients when writing 
/// vCard 2.1 or vCard 3.0.
/// This example uses the nuget package TimeZoneConverter 
/// ( https://www.nuget.org/packages/TimeZoneConverter/ ).
/// </summary>
public class TimeZoneIDConverter : ITimeZoneIDConverter
{
    // Converts, e.g., "Europe/Berlin" to +01:00
    public bool TryConvertToUtcOffset(string timeZoneID, out TimeSpan utcOffset)
    {
        // Convert at least IANA time zone names:
        if (TimeZoneConverter.TZConvert.TryGetTimeZoneInfo(timeZoneID, out TimeZoneInfo? tzInfo))
        {
            utcOffset = tzInfo.BaseUtcOffset;
            return true;
        }

        utcOffset = default;
        return false;
    }
}

Reference