Welcome

This topic contains the following sections:

Personal Data Interchange Library Features

The EWSoftware Personal Data Interchange (PDI) Library presents you with a complete set of classes that let you have access to all objects, properties, parameter types, and data types as defined by the vCard (RFC 2426 and 6350), vCalendar, and iCalendar (RFC 2445) specifications. Using these classes, you can read and write data files in a well-defined format used by many applications on various platforms to exchange personal information such as business cards, telephone numbers, addresses, dates and times of appointments, etc. A recurrence engine is also provided that allows you to easily and reliably calculate recurrence dates and times for even the most complex recurrence patterns. The classes can be used in both desktop applications and web applications.

For flexibility, a number of the data type classes such as Duration, Period, DateTimeCollection, and the Recurrence class are implemented as standalone classes that can be used independently of the PDI calendar and vCard classes. This lets you take advantage of their features without including any unnecessary overhead.

The library contains the following features:

  • The library is built in 100% .NET managed code written in C# and provides a complete implementation of the vCard 2.1, vCard 3.0 (RFC 2426), vCalendar 1.0, and iCalendar 2.0 (RFC 2445) specifications. Partial support for the Infrared Mobile Computing (IrMC) 1.1 specification is also provided to allow working with vNote objects. Partial support is included for vCard 4.0 (RFC 6350).

  • Objects can be created by parsing them from a data stream such as a string, text file, or a URL or in code using a rich, consistent object model.

  • Type-safe, enumerable, searchable, sortable collection classes are provided for all of the objects that need a collection class. Almost all of the collections also have overloaded Add and AddRange methods to quickly and easily add values to the them. Collections containing objects with unique IDs (vCard, event, journal, to-do, and free/busy items) can be indexed using a unique ID value.

  • PDI object collections support standard data binding on the collection, top level properties, and child properties up to three levels deep.

  • Some of the classes like Holiday and Recurrence support serialization (XML, SOAP, and binary).

  • The recurrence engine which supports all iCalendar 2.0 recurrence patterns and options is separate from the PDI data classes. As such, if all you need is recurrence pattern generation without support for exception dates or other features provided by the calendar classes, you only need to reference one assembly containing just those classes that you need.

  • The recurrence engine is very fast and supports the full date/time range of the .NET DateTime data type (01/01/0001 12:00:00AM to 12/31/9999 11:59:59PM).

  • The Recurrence class provides a type-safe enumerator so that you can use a recurrence object in a foreach loop to enumerate the entire set of date/times generated by a recurrence pattern. Alternately, you can use various class methods to obtain an enumerable list of all instances or a range of instances generated by the pattern.

  • Additional classes are provided to define and determine the dates on which holidays fall (Holiday and HolidayCollection). These can be used in conjunction with the recurrence engine to filter out recurrence dates when they fall on a holiday. They can also be used by themselves for any other purpose you may have that requires tracking holiday dates.

  • Holidays can be defined as fixed (occurring on a specific month and day with optional support for moving them to the preceding Friday if they fall on a Saturday or the following Monday if they fall on a Sunday) or as floating (occurring on a specific instance of a day of the week in a given month). As with the recurrence engine, the holiday classes supports the full date/time range of the .NET DateTime data type.

  • When the recurrence engine is used in conjunction with the PDI calendar classes (VEvent, VToDo, and VJournal), full support is provided for multiple recurrence rules, recurrence dates, exception rules, and exception dates so that very complex recurrence sets can be generated. Instances can be generated in local time or the time zone of the component.

  • Parser classes are provided to read vCard, vCalendar, and iCalendar files. The parsers are fast and flexible enough to handle PDI data in any format regardless of spacing, line folding, text case, and object, property, or parameter order. Simply pass them a string, filename, URL, or a TextReader-derived stream class and they will do all of the work necessary to load the objects.

  • All PDI classes are able to write themselves out in the appropriate format based on the specification version including encoding and folding lines where appropriate. Simply use their ToString method or use the WriteToStream method to save them to a TextWriter-derived stream class.

  • Encoding and decoding support is built into the property classes and they can handle all defined types including inline quoted-printable and Base64 encoded binary data.

  • Switching between specification versions is achieved by setting the Version property on a top-level object such as VCard or VCalendar.

  • Support for iCalendar 2.0 time zones is provided. The VTimeZone and VTimeZoneCollection classes contain information about time zone objects found in an iCalendar file. For calender properties that utilize the TimeZoneID (TZID) parameter, their date/time values are converted to/from local time automatically. You can also access the underlying date/time for the time zone itself.

  • Utility methods are provided in the VCalendar class to convert date/times from one time zone to another and between a time zone and local time. The methods are Daylight Saving Time aware and will take it into account when necessary based on the observance rules defined in the VTimeZone objects.

  • Other methods are provided in the components to apply a time zone with date/time adjustment to the calendar as a whole or to individual components and to set a time zone ID without changing the date/time values in the calendar as a whole or in individual components.

  • Some Windows Forms controls are provided for interacting with the PDI classes (i.e. a holiday manager user control, holiday properties dialog, recurrence pattern user controls, and a recurrence properties dialog).

  • An ASP.NET web server control is provided for editing recurrence patterns in a user-friendly fashion similar to the Windows Forms Recurrence Pattern control.

Installing the Assemblies in the Global Assembly Cache

All of the EWSoftware.PDI assemblies have strong names. As such, you can install the assemblies in the Global Assembly Cache (GAC) if so desired. To do so, use the GACUTIL command line tool as follows replacing the path to the assemblies to match the installed location on your system:

 
gacutil -i \GH\TFS01\EWSPDI\Deployment\EWSoftware.PDI.dll
gacutil -i \GH\TFS01\EWSPDI\Deployment\EWSoftware.PDI.Data.dll
gacutil -i \GH\TFS01\EWSPDI\Deployment\EWSoftware.PDI.Web.Controls.dll
gacutil -i \GH\TFS01\EWSPDI\Deployment\EWSoftware.PDI.Windows.Forms.dll

To remove the assemblies from the Global Assembly Cache, use the GACUTIL command line tool as follows:

 
gacutil -u EWSoftware.PDI
gacutil -u EWSoftware.PDI.Data
gacutil -u EWSoftware.PDI.Web.Controls
gacutil -u EWSoftware.PDI.Windows.Forms

Installing the Controls in the Visual Studio Toolbox

The Windows Forms controls and the web server controls provide rich design-time support. They appear on the design surface as they do at runtime. Their properties can be edited using the normal Properties Window. Installing the controls in the Visual Studio toolbox will allow you to use the controls at design time by dragging them from the toolbox and dropping them on to your form. To install them for the first time or to refresh the toolbox after the control assemblies have been updated, do the following:

  • Open the toolbox window. Right click on it and select the Show All option.

  • If you do not currently have a tab for the control library, create one by right clicking on the toolbox window, selecting Add Tab, and then typing in a name for the tab such as EWSoftware PDI Controls.

  • Click on the tab for the control library so that it is selected.

  • If the tab is not empty, remove the existing controls by doing the following:

    • Right click on the toolbox tab and select Choose Items....

    • In the dialog box that opens, select the .NET Framework Components tab. Click on the Namespace header to sort the list of controls by namespace.

    • Locate the EWSoftware.PDI namespaces and uncheck all of the controls in those namespaces.

    • Click the OK button and the controls will be removed from the toolbox. You are now ready to add the new version of the control library.

  • To add the controls to the toolbox tab, do the following:

    • Right click on the toolbox tab and select Choose Items....

    • In the dialog box that opens, select the .NET Framework Components tab. Click on the Namespace header to sort the list of controls by namespace.

    • Click on the Browse button and navigate to where the EWSoftware.PDI.Web.Controls.dll and EWSoftware.PDI.Windows.Forms.dll assemblies are stored. Select one and click the Open button. This will add the controls in the assembly to the list in the dialog box. They will all be selected and checked by default. Repeat this step for the other assembly.

    • Click the OK button to complete the process and the new controls will appear in the toolbox tab.

Note that both recurrence pattern controls are called RecurrencePattern so you may want to put each one in its own tab or right click on them and use the Rename option to change their names to their fully qualified namespace to keep them straight. However, this is not a necessity as when developing a web project, the Windows Forms control will be disabled in the toolbox and when developing a Windows Forms application, the web control will be disabled in the toolbox.

Using the Assemblies in Your Projects

  Tip

NuGet packages are available for the libraries. Search for the package names:

  • EWSoftware.PDI - Contains the date utility classes, recurrence engine, and holiday classes.

  • EWSoftware.PDI.Data - Contains the classes used to create and consume vCard, vCalendar, and iCalendar files.

  • EWSoftware.PDI.Web.Controls - Contains some web controls that can be used to edit recurrence settings.

  • EWSoftware.PDI.Windows.Forms - Contains some Windows Forms controls that can be used to edit holiday calculation settings and to edit recurrence settings.

The date utility and recurrence classes can be found in the assembly EWSoftware.PDI.dll. The calendar and vCard classes can be found in the assembly EWSoftware.PDI.Data.dll. The web server controls can be found in the assembly EWSoftware.PDI.Web.Controls. The Windows Forms controls can be found in the assembly EWSoftware.PDI.Windows.Forms.dll. In order to use the classes, add a reference to the appropriate assembly in your project. To add the reference, open your project in Visual Studio, open the Solution Explorer pane of the project, right click on the References folder, select Add Reference..., click the Browse button and navigate to the folder in which you placed the assemblies, and finally select the appropriate assembly and click OK to close the dialogs and add the reference.

In code modules that use classes from the EWSoftware.PDI namespaces, you will have to add a using statement (Imports in VB.NET) for one or more of the following namespaces:

  • EWSoftware.PDI - Date utility classes, recurrence engine, holiday classes.

  • EWSoftware.PDI.Objects - Calendar and vCard object classes.

  • EWSoftware.PDI.Parser - Calendar and vCard parser classes.

  • EWSoftware.PDI.Properties - Calendar and vCard property classes.

  • EWSoftware.PDI.Web.Controls - Web server control classes.

  • EWSoftware.PDI.Windows.Forms - Windows Forms control classes.

Demonstration Applications

Windows Forms and web applications in C# and VB.NET are provided that demonstrate the basic use of the classes and controls.

Demo App

Purpose

PDIDatesTest

This is a console mode application that runs through a few simple configurations to test the basics in the date utility, holiday, and recurrence classes found in the EWSoftware.PDI namespace.

PDIParserTest

This is a console mode application used to test the EWSoftware.PDI.Data namespace classes. It scans the specified folder for vCard and vCalendar/iCalendar files and loads them to test the parser. It then saves them to another specified folder so that the contents can be compared to verify that the PDI output methods are working as expected. Note that the content order and formatting may change but the information overall should still be the same. Some sample files of all types are included in the .\PDIFiles folder.

PDIWinFormsTest

This application is used to demonstrate various features of the EWSoftware PDI classes found in all of the namespaces. With it, you can:

  • Test the holiday classes, the interactive holiday manager Windows Forms control, and the holiday editor Windows Forms dialog box.

  • Test the recurrence parser, recurrence rule generation, and the interactive recurrence pattern Windows Forms controls and dialog box.

  • Test the calendar event parser and calendar recurrence generation with time zone support.

  • Test the time zone conversion methods in the VCalendar class.

RFC2445RecurTest

This console mode application creates the example recurrence patterns given in the RFC 2445 iCalendar specification starting on page 118 and generates the instances for each one. Rather than parsing the information from strings, this demonstration shows how to create the patterns using the API. The first part calculates instances using only the Recurrence class (all instances are expressed in local time). The second part calculates instances using the calendar classes with time zone support (results are shown for the US-Eastern time zone used in the specification examples and in local time).

vCardBrowser

This is a Windows Forms demonstration application that shows how to load, save, and manage a set of vCards including how to edit the various vCard properties. Some sample vCard files are included in the .\PDIFiles folder.

CalendarBrowser

This is a Windows Forms demonstration application that shows how to load, save, and manage vCalendar and iCalendar files including how to edit the properties on the various components. It also demonstrates the ways that time zone components can be used with iCalendar files. Some sample calendar files are included in the .\PDIFiles folder.

PDIWebDemoCS / PDIWebDemoVB

This is a web application that demonstrates various aspects of the EWSoftware PDI classes (a C# and a VB.NET version are included). It covers most of the same areas as the other Windows Forms applications and shows several examples of data binding with the collection objects. It also demonstrates the recurrence pattern editor web server control.

To try out the demo web applications, open the projects in Visual Studio. Once built, they are set up to run using the development web server. The startup page in each is Default.aspx. If you are using a remote server, you will need to set up the virtual directories and copy the demo application files to the server locations.

See Also