Welcome
This topic contains the following sections:
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.
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
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.
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.
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. |
