Adding iCalendar Support to Your Program - Part 1

• Download source files - 229.89 KB

Introduction

This article describes how to load and view iCalendars by using the DDay.iCal library. I will cover more advanced topics, such as creating, editing, and serializing iCalendars in my next article.

In this article, I will walk you through creating a console application that will load and display upcoming events to the user. I've also included an example project that demonstrates how to add this kind of support to an ASP.NET web application.

Background

Many programmers have worked with adding some kind of calendar support to an application - from displaying upcoming events on a web site, to allowing personalized calendars, with the ability to alter them.

So, thousands of programmers, all adding calendar support to their applications. So, what's the problem with that? The historical answer is that no (or very few) programmers followed any kind of standard to implement their calendars. So, if you needed to accomplish anything else with the calendar that your original application didn't support, you'd have to write it by hand.

Also, these ad-hoc calendars are only viewable from the application that wrote them. What if you want to allow for recurrences in your calendar, so an event can recur "every 2^nd-to-last Sunday of the month?" What if you want to publish your calendar, so others can subscribe to it, and view it from the calendar program they prefer? What if you want to display and manipulate calendars from multiple sources, including sources that you may not have control over?

These are some of the problems the iCalendar standard solves for us. If you didn't already know -- iCalendar is a W3C recommendation known as RFC 5545. You can find it here.

Using the Code

To begin, open Visual Studio and create a "Windows Console Application" project. Then, if you haven't already done so, download the latest binary version of DDay.iCal from SourceForge.net. Once you've done that, you simply need to add a reference to DDay.iCal.dll from your project (i.e. click "Add Reference" from the "Project" menu).

Then, add the following to the top of the Program.cs file:

using DDay.iCal;

You're now ready to load your first iCalendar! There are multiple ways you can load iCalendars, ranging from simply loading the file from your local filesystem, to loading from a WebDAV or CalDAV store, to loading from a database. The possibilities are endless; however, in this article, we'll focus on simply loading the file from your local filesystem. Add the following code to your Main() method (of course, replacing the path with the actual path to your iCalendar file).

// Load the calendar file
IICalendarCollection calendars = iCalendar.LoadFromFile(@"path\to\your\icalendar.ics");

Congratulations, you've loaded your iCalendar, and are ready to work with it! For now, let's display the events that occur today:

//
// Get all events that occur today.
//
IList&occurrence> occurrences = calendars.GetOccurrences
	(DateTime.Today, DateTime.Today.AddDays(1));

Console.WriteLine("Today's Events:");

// Iterate through each occurrence and display information about it
foreach (Occurrence occurrence in occurrences)
{
    DateTime occurrenceTime = occurrence.Period.StartTime.Local;
    IRecurringComponent rc = occurrence.Source as IRecurringComponent;
    if (rc != null)
        Console.WriteLine(rc.Summary + ": " + occurrenceTime.ToShortTimeString());
}

That's it! To be clear, calendars.GetOccurrences(...) returns a list of Occurrence objects. Occurrence objects describe each occurrence, including the date/time the occurrence happens, and a reference to the original component that generated the occurrence. We cast the Source of the occurrence to an IRecurringComponent, and display its properties.

So, now we've displayed all the events that occur today. Let's display all of the upcoming events that will occur within the next 7 days:

//
// Get all occurrences for the next 7 days, starting tomorrow.
//
occurrences = calendars.GetOccurrences
		(DateTime.Today.AddDays(1), DateTime.Today.AddDays(7));

Console.WriteLine(Environment.NewLine + "Upcoming Events:");

// Start with tomorrow
foreach (Occurrence occurrence in occurrences)
{
    DateTime occurrenceTime = occurrence.Period.StartTime.Local;
    IRecurringComponent rc = occurrence.Source as IRecurringComponent;
    if (rc != null)
        Console.WriteLine(rc.Summary + ": " + occurrenceTime.ToString());
}

As you can see, this code is nearly identical to "Today's Events", with a slight difference at calendars.GetOccurrences(...). We also display the full date/time of the recurrence this time.

Note: If you're only interested in certain kinds of components (i.e. Events, Todos, etc.), then you can get occurrences for only those events using the generic version of GetOccurrences (i.e. calendars.GetOccurrences<IEvent>(...)).

Final Code

Here's the final result of Program.cs:

using System;
using System.Collections.Generic;
using System.Text;

// Required DDay.iCal namespace
using DDay.iCal;

namespace ConsoleApplication1
{
    class Program
    {
        static void Main(string[] args)
        {
            // Load the calendar file
            IICalendarCollection calendars = iCalendar.LoadFromFile(@"Business.ics");

            //
            // Get all events that occur today.
            //
            IList&occurrence> occurrences = calendars.GetOccurrences
				(DateTime.Today, DateTime.Today.AddDays(1));

            Console.WriteLine("Today's Events:");

            // Iterate through each occurrence and display information about it
            foreach (Occurrence occurrence in occurrences)
            {
                DateTime occurrenceTime = occurrence.Period.StartTime.Local;
                IRecurringComponent rc = occurrence.Source as IRecurringComponent;
                if (rc != null)
                    Console.WriteLine(rc.Summary + ": " + 
				occurrenceTime.ToShortTimeString());
            }

            //
            // Get all occurrences for the next 7 days, starting tomorrow.
            //
            occurrences = calendars.GetOccurrences
		(DateTime.Today.AddDays(1), DateTime.Today.AddDays(7));

            Console.WriteLine(Environment.NewLine + "Upcoming Events:");

            // Start with tomorrow
            foreach (Occurrence occurrence in occurrences)
            {
                DateTime occurrenceTime = occurrence.Period.StartTime.Local;
                IRecurringComponent rc = occurrence.Source as IRecurringComponent;
                if (rc != null)
                    Console.WriteLine(rc.Summary + ": " + occurrenceTime.ToString());
            }
        }
    }
}

Points of Interest

For more information, visit the DDay.iCal homepage at ddaysoftware.com.

Many apologies that it's taken so long to update this article. I'll now be providing more frequent updates.

History

• 04/14/2010 - Updated to version 1.0 Alpha
• 03/09/2007 - Posted