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. |
