Programmatically Creating and Updating Appointments in Windows 8.1

Introduction

At Build 2013, Microsoft announced Windows 8.1. Windows 8.1 introduces more than 4000 new APIs to allow developers to achieve even more than what Windows 8 offered.

One of the new Windows 8.1 APIs is the set of APIs in the Windows.ApplicationModel.Appointments namespace. The APIs under the Windows.ApplicationModel  namespace offer a Windows application access to core system functionality and run-time information about its application package.

With Windows 8,1, applications use contracts to declare how they intend to interact with other applications and with the operating system.

The Windows.ApplicationModel.Appointments namespace contains APIs needed to represent an appointment in a calendar.

The Windows.ApplicationModel.Appointments contains the following classes:

Class

Description

Appointment

This represents an appointment in a calendar.

AppointmentInvitee

This represents an invitee of an appointment

AppointmentManager

This is the class that is responsible for interacting with the user’s Appointments provider from application data.

AppointmentOrganizer

This represents the organizer of an appointment in the calendar.

AppointmentRecurrence

This represents the recurrence of an appointment in the calendar.

In Windows 8, the ability to create appointments was restricted to only the Calendar application. With Windows 8.1, applications can now add events onto the calendars. To add an appointment, the application needs to create an appointment object and then call the operating system to add the appointment via the Add Event dialog.

The user then has to consent to add the appointment on the calendar. If the user agrees and the event is added, an identifier is returned to the application that can be used to update the appointment details in the future.

At the time of writing this article, there are no published details as to how an application can register to be a calendar itself (besides the built-in Calendar app).

The workflow to add an appointment to the Calendar is below:

Your customer application -> Windows Runtime -> Launch action verb + Appointment object -> user accepts -> Appointment added on Calendar.

The APIs used by Appointment Manager to show the time frame and to add appointments to the user’s choice of calendar app are: Windows.ApplicationModel.Appointments.AppointmentManager.ShowTimeFrameAsync and Windows.ApplicationModel.Appointments.AppointmentManager.ShowAddAppointmentAsync.

Hands On

At the time of writing this article, there seems to be a bug in the Windows 8.1 image that has been released as the beta because the default Calendar application does not seem to be registered as the default Appointment provider.

Start Visual Studio 2013 Express Preview and create a new Windows Store Project of type BlankApp called Windows8.1AppointmentDemo.

New Windows Store Project
New Windows Store Project

To keep our application simple, we will only try to create a non-recurring appointment with as little detail as possible. We will add controls for the following information about our appointment: Subject, Location, Details. We will put textboxes for the above information and a button to Add the Appointment.

Note that the UI will look like the screenshot below for our trivial attempt to add an appointment.

UI
UI

Next, we will implement the logic to create the Appointment object.

On the click event of the “Create Appointment” button, we will add the code to create an object of the Appointment class.

We will begin by adding the inclusion of the  Windows.ApplicationModel.Appointments namespace.

// MainPage.xaml.cs
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Runtime.InteropServices.WindowsRuntime;
using Windows.Foundation;
using Windows.Foundation.Collections;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Controls.Primitives;
using Windows.UI.Xaml.Data;
using Windows.UI.Xaml.Input;
using Windows.UI.Xaml.Media;
using Windows.UI.Xaml.Navigation;
using Windows.ApplicationModel.Appointments;

Next, in the click event handler, we will add the code as shown below.

For our application, we will assume that we want to create a 30 minute appointment today at 10 pm.

private async void buttonCreateAppointment_Click(object sender, RoutedEventArgs e)
        {
            appointment = new Appointment();
            // We will assume that we want to create an appointment for today at 10 pm in the night for 30 minutes.
            var date = (DateTimeOffset)DateTime.Now;
            var time = (TimeSpan)new TimeSpan(22, 0, 0);
            var timeZoneOffset = TimeZoneInfo.Local.GetUtcOffset(DateTime.Now);
            var startTime = new DateTimeOffset(date.Year, date.Month, date.Day, time.Hours, time.Minutes, 0, timeZoneOffset);
            appointment.StartTime = startTime;
 
            // Subject
            if (textBoxSubject.Text == "")
                appointment.Subject = "Test Appointment Subject";
            else
                appointment.Subject = textBoxSubject.Text;
 
 
 
            // Location
            if (textBoxLocation.Text == "")
                appointment.Location = "In Windows 8.1 land";
            else
                appointment.Location = textBoxLocation.Text;
 
 
            // Details
            if (textBoxDetails.Text == "")
                appointment.Details = "Test Appointment details";
            else
                appointment.Details = textBoxDetails.Text;
 
 
            appointment.Duration = TimeSpan.FromMinutes(30);
            var rect = GetElementRect(sender as FrameworkElement);
            String appointmentId = await Windows.ApplicationModel.Appointments.AppointmentManager.ShowAddAppointmentAsync(appointment, rect, Windows.UI.Popups.Placement.Default);
            if (appointmentId != String.Empty)
            {
 
                textBoxResult.Text = "Appointment Id: " + appointmentId;
            }
            else
            {
                textBoxResult.Text = "Appointment not added.";
            }
        }}

Please note that because the AppointmentManager.ShowAddAppointmentAsync API is async, we need to decorate the click event handler as an async operation.

In the method above, we need to create a rectangle (window) to display the popup of the operating system. That is implemented in the following method.

private Windows.Foundation.Rect GetElementRect(FrameworkElement element)
        {
            Windows.UI.Xaml.Media.GeneralTransform buttonTransform = element.TransformToVisual(null);
            Windows.Foundation.Point point = buttonTransform.TransformPoint(new Windows.Foundation.Point());
            return new Windows.Foundation.Rect(point, new Windows.Foundation.Size(element.ActualWidth, element.ActualHeight));
        }

Now, our basic application is complete.

We can run this application and try to create an appointment. If you are having trouble following along, you can download a copy of the sample source code from below.

Testing our application

When we run our application, we will notice that it fails after showing a dialog that there are no appointment providers. This seems to be a bug in Windows 8.1 and hopefully it will be fixed soon so that the default Calendar app becomes the Appointments Provider.

No Appointment Providers
No Appointment Providers

Summary

In this article we learned about how Windows 8.1 applications can create appointments by invoking APIs. I hope you have found this information useful.

About the Author

Vipul Patel is a Program Manager currently working at Amazon Corporation. He has formerly worked at Microsoft in the Lync team and in the .NET team (in the Base Class libraries and the Debugging and Profiling team). He can be reached at vipul.patel@hotmail.com

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read