ProjectsWebsiteBlog

Breaking Changes

Listing all the breaking changes.

There are new releases of VisualCard that cause breaking changes, so you'll need to take them into consideration when upgrading your program to use later versions of VisualCard. Here are the version upgrade paths:

VisualCard v0.x to v1.0

During the v0.x upgrade to v1.0, you'll need to consider the following:

Main ALTID is now -1

The main ALTID number used to be 0, because you could specify it or not in a property and the ALTID support was half-implemented. Now, because of the recent improvements to the parsing techniques that VisualCard uses, you can no longer implement some of the different property instances that have its ALTID value of 0, such as N for name information. All main properties without their positive ALTID values will have their ALTID of -1, meaning that it's a main instance. For example, VisualCard will error out when seeing such properties implemented in a contact's vCard like this:

N:Navasquillo;Neville;Neville\,Nevile;Mr.;Jr.
N;ALTID=0;LANGUAGE=de:NAVASQUILLO;Neville;Neville\,Nevile;Mr.;Jr.

Enforcing the correct types

In earlier versions of VisualCard, it allowed any and all of the types, even those that are not supported in all the RFC documents as specified in the How to use page. Starting from VisualCard v1.0, the following base types are supported:

  • HOME, WORK, and PREF

  • X-nonstandard types

The extra types are written in a separate page, Card Parts.

If the type that is specified is not supported by a property, such as warehouse type in the address property, VisualCard will throw an exception. This will break cards that are generated in a non-standard way.

VisualCard v1.x to v3.0

During the v1.x upgrade to v3.0, you'll need to consider the following:

Moved extra features to VisualCard.Extras

namespace VisualCard.Converters
{
    public static class AndroidContactsDb
    public static class MeCard
}

namespace VisualCard.Extras
{
    public static class CardGenerator
}

We've moved extra features that just make use of the VisualCard base library to its own library, VisualCard.Extras. As a result, the above classes have been moved to their appropriate namespace defined by that library.

  • VisualCard.Converters -> VisualCard.Extras.Converters

  • VisualCard.Extras -> VisualCard.Extras.Misc

You should change the using clauses to be able to continue using these extensions.

MALARM array enum name changed

CalendarPartsArrayEnum.cs
public enum CalendarPartsArrayEnum
{
    (...)
    NoteAlarm,
    (...)
}

Due to missing parts from the vCalendar 1.0 original specification text output, we've had to change NoteAlarm's name to MailAlarm so that it doesn't mislead developers. As a result, MALARM is now considered as a proper alarm with mail as alarm method. We've also changed the class name like so:

MailAlarmInfo.cs
- public class NoteAlarmInfo : BaseCalendarPartInfo, IEquatable<NoteAlarmInfo>
+ public class MailAlarmInfo : BaseCalendarPartInfo, IEquatable<MailAlarmInfo>

You should change all references to the NoteAlarmInfo class and to the NoteAlarm enum value so that they point to the following:

  • CalendarPartsArrayEnum.MailAlarm

  • MailAlarmInfo

Used DateTimeOffset in date-related types

AnniversaryInfo.cs
// This also applies to all type instances that used DateTime
public DateTime Anniversary { get; }

We've changed the date definitions from DateTime to DateTimeOffset as there is confusion when dealing with time offsets as explained here. VisualCard deals with date and time which may be described as local time according to a specific time zone.

You don't need to do anything unless you do something that breaks the property call.

Used periods in RecDateInfo

RecDateInfo.cs
public DateTimeOffset[]? RecDates { get; }

Recurrence date information can be get from either a date and time pair or a date/time and a duration string representation. We've used an array of TimePeriod instead of DateTimeOffset to give better support for vCalendar files that contain recurrence periods.

You'll have to get either a start date or an end date from the array, depending on what you're dealing with, to be able to continue using the recurrence date information.

Changed how string and integer parts are handled

Card.cs
public string GetString(StringsEnum key)
Calendar.cs
public string GetString(CalendarStringsEnum key)
public double GetInteger(CalendarIntegersEnum key)

Amidst the recent improvements that affected how the strings and the integers are returned, we needed to add support for extra properties, type parsing, and value type parsing. As a result, we've changed these functions so that they return the corresponding ValueInfo classes:

  • Cards: CardValueInfo

  • Calendars: CalendarValueInfo

Consult the parts documentation for more information as to how to use these class instances.

ArgumentInfo implemented

BaseCardPartInfo.cs
public virtual string[] Arguments { get; internal set; } = [];
BaseCalendarPartInfo.cs
public virtual string[]? Arguments { get; internal set; }

ArgumentInfo provided a class instance that allowed you to have a better look at the arguments after either a vCard or a vCalendar has been parsed. The property is still there, but we've changed it to become an array of ArgumentInfo so that you can handle the arguments with more care.

As a result, we've removed the ArgumentValues property as it's been replaced with the ArgumentInfo class instance.

You'll need to change how you handle the Arguments property, depending on the purpose. If you're using ArgumentValues, stop using it and use the Arguments property as the latter handles this exact use case.

Card kind property changed

Card.cs
public string CardKind

We've introduced the CardKind enumeration, so we've decided to make the above property return that enumeration.

The string representation is still available, but moved to the CardKindStr property.

VisualCard v3.0 to v3.1

During the v3.0 upgrade to v3.1, you'll need to consider the following:

PropertyInfo is now more useful

Base*PartInfo.cs / *ValueInfo.cs
public virtual ArgumentInfo[] Arguments { get; internal set; } = [];

The following classes are affected with this change:

  • BaseCardPartInfo

  • CardValueInfo

  • BaseCalendarPartInfo

  • CalendarValueInfo

The above property has been edited so that it points to the relevant PropertyInfo instance that contains the Arguments property, which has exactly the same amount of information that you'd obtain from there.

To be able to access this property, you need to access the Property value in a card part or a value info class.

VisualCard v3.1 to v3.2

During the v3.1 upgrade to v3.2, you'll need to consider the following:

CardValueInfo and CalendarValueInfo merged

CardValueInfo.cs
public class CardValueInfo<TValue> : IEquatable<CardValueInfo<TValue>>
{
    (...)
}
CalendarValueInfo.cs
public class CalendarValueInfo<TValue> : IEquatable<CalendarValueInfo<TValue>>
{
    (...)
}

We have merged the two above classes into the ValueInfo class found in the main VisualCard library as we have spotted common properties that are found in both the above classes. As we want to get rid of redundancy, we've merged them together.

You can now use the ValueInfo class.

VisualCard v3.2 to v4.0

During the v3.2 upgrade to v4.0, you'll need to consider the following:

Refactored some common code to the common library

As part of the API refinement that was planned for v4.0, we've migrated the following component-agnostic code to the common library, which is VisualCard.Common:

  • ArgumentInfo [class]

  • PropertyInfo [class]

  • RecurrenceParser [class]

  • RecurrenceRule [class]

  • RecurrenceRuleFrequency [enum]

  • VcardCommonTools -> CommonTools [class]

  • TimePeriod [class]

  • PartType [enum]

  • ExtraInfo [class]

  • XNameInfo [class]

  • ValueInfo [class]

In addition to that, we've introduced the BasePartInfo that BaseCardPartInfo and BaseCalendarPartInfo inherit from to reduce code repetition, such as the X-nonstandard and the extra part info classes that are component-agnostic.

None of the functions have been removed, so all you have to do is to just update the using clause.

Separated IANA and non-standard properties

PartsArrayEnum.cs and StringsEnum.cs
public enum PartsArrayEnum
public enum StringsEnum

We've separated the IANA and the non-standard properties as a result of the above breaking change related to VisualCard.Common, because IANA and non-standard properties can be found in both the card and the calendar instances.

You can no longer use the GetPartsArray() function and the PartsArray property to get IANA and non-standard properties. You should use the GetExtraPartsArray() function and the ExtraParts property instead.

Separated PropertyInfo from ValueInfo and base part classes

PropertyInfo.cs
public class PropertyInfo : IEquatable<PropertyInfo?>

PropertyInfo used to hold several property information properties that allowed you to get more information about a property, such as a number of arguments.

Over time, while we were making major structural changes to simplify the codebase, PropertyInfo was an obstacle that got in our way, so we had to basically move relevant properties to ValueInfo and base part classes. The following properties have been moved:

  • AltId

  • Group

  • NestedGroups

  • Arguments

  • Encoding

  • Type

The above properties have been moved from ValueInfo's Property property and from the base part classes' Property property, both of which have been removed, to the ValueInfo and the base part classes themselves. For example, if you want to get an encoding from part that represents one of the two classes, you can now use part.Encoding instead of part.Property?.Encoding.

Last updated