Calendar Management in Cloud Calendars


Requirements: Cloud Calendars

Contents

Introduction

Cloud Calendars includes components for managing calendars and events in popular cloud services: GoogleCalendars for Google Calendar, and Office365Calendars for Microsoft 365 (using the Microsoft Graph API). Both components support listing, creating, updating, and deleting calendars and events, and Office365Calendars also supports event attachments. This guide shows how to use each of them, with examples in C#.

Cloud Calendars also includes components for managing tasks, which are covered in our Task Management in Cloud Calendars article.

Authorization

Both components use OAuth 2.0 for authorization, which is built into the components through the OAuth property and the Authorize method. The authorization server URLs and scopes for each service are set by default, so in most cases only the client ID and client secret of the application need to be set. When Authorize is called, the component launches a browser so that the user can sign in and grant access, and then obtains an access token, which is used in all subsequent requests.

GoogleCalendars gcal = new GoogleCalendars();
gcal.OAuth.ClientProfile = CloudOAuthClientProfiles.cocpApplication;
gcal.OAuth.GrantType = OAuthSettingsGrantTypes.cogtAuthorizationCode;
gcal.OAuth.ClientId = "CLIENT_ID";
gcal.OAuth.ClientSecret = "CLIENT_SECRET";
gcal.Authorize();
Office365Calendars office365 = new Office365Calendars();
office365.OAuth.ClientProfile = CloudOAuthClientProfiles.cocpApplication;
office365.OAuth.GrantType = OAuthSettingsGrantTypes.cogtAuthorizationCode;
office365.OAuth.ClientId = "CLIENT_ID";
office365.OAuth.ClientSecret = "CLIENT_SECRET";
office365.Authorize();

The default scopes are https://www.googleapis.com/auth/calendar for GoogleCalendars, and offline_access calendars.readwrite user.read for Office365Calendars. They can be changed with the OAuth.AuthorizationScope field. By default, a refresh token is also requested, which can be used to obtain new access tokens without user interaction.

For more information, including how to persist refresh tokens and how to authorize web and unattended applications, please see our OAuth Authorization in /n software Cloud Products article.

Working with the Collections

Both components store calendars and events in the Calendars and Events collections, and the methods that modify them work in the same way:

  • ListCalendars and ListEvents clear the collection, and then add each item that is returned. The CalendarList and EventList events also fire for each item.
  • CreateCalendar, CreateEvent, and GetEvent add the new or retrieved item at the beginning of the collection (index 0).
  • UpdateCalendar and UpdateEvent take the index of the item to update, send the item to the server, and then move the updated item to the beginning of the collection.
  • DeleteCalendar and DeleteEvent do not remove the item from the collection. It is removed the next time the collection is listed.

To create an item with more than the basic information that the Create methods accept, create it, set the fields of the item at index 0, and then call the Update method with index 0.

Both components return calendars and events in pages of 100 by default, which can be changed with the CalendarsPageSize and EventsPageSize configuration settings. If there are more items, the ListCalendarsMarker configuration setting or the ListEventsMarker property is populated, and calling the method again adds the next page to the end of the collection:

// List all calendars.
do
{
  gcal.ListCalendars();
} while (gcal.Config("ListCalendarsMarker").Length > 0);

GoogleCalendars

Calendars

To list the calendars of the user, call ListCalendars. Each calendar in the Calendars collection includes fields such as Id, Summary (the name of the calendar), Description, and Location.

To create a calendar, call CreateCalendar with its name. Note that creating a calendar with the same name as an existing calendar creates a second calendar, with a different ID.

// Create a calendar, and then set its description.
gcal.CreateCalendar("Team Calendar");
gcal.Calendars[0].Description = "Meetings and events for the team.";
gcal.UpdateCalendar(0);
string calendarId = gcal.Calendars[0].Id;

To delete a calendar and all of its events, call DeleteCalendar with its ID:

// Delete the calendar named "Old Calendar".
gcal.ListCalendars();
for (int i = 0; i < gcal.Calendars.Count; i++)
{
  if (gcal.Calendars[i].Summary == "Old Calendar")
  {
    gcal.DeleteCalendar(gcal.Calendars[i].Id);
    break;
  }
}

The ListColors method retrieves the colors that are available for calendars and events into the Colors collection, which can be used with the ColorId field of a calendar or event.

Events

To list the events in a calendar, call ListEvents with the ID of the calendar, and optionally a time range. The ID of the primary calendar of the user can also be specified as primary. The time range parameters filter events that end after the first time and start before the second time, and must be RFC 3339 timestamps with a time zone offset (e.g., 2026-12-01T00:00:00Z). To list all events, pass empty strings instead.

// List the events in December 2026, across all pages.
do
{
  gcal.ListEvents("primary", "2026-12-01T00:00:00Z", "2027-01-01T00:00:00Z");
} while (gcal.ListEventsMarker.Length > 0);

foreach (GCalEvent ev in gcal.Events)
{
  Console.WriteLine(ev.Summary + ": " + ev.StartDateTime + " - " + ev.EndDateTime);
}

To create an event, call CreateEvent with its summary, start time, end time, and calendar ID. The times are in UTC, in the format yyyy-MM-ddTHH:mm:ss. To create an all-day event, specify only the dates instead (e.g., 2026-12-12). Attendees and reminders can then be set on the new event before calling UpdateEvent. Since an event can have several attendees, the attendee fields apply to the attendee selected by AttendeeIndex, after AttendeesCount has been set, and the reminder fields work in the same way.

gcal.CreateEvent("Project Review", "2026-12-12T16:00:00", "2026-12-12T17:00:00", calendarId);
GCalEvent ev = gcal.Events[0];
ev.Description = "Quarterly review of the project.";
ev.Location = "Conference Room A";

// Add two attendees, the second of which is optional.
ev.AttendeesCount = 2;
ev.AttendeeIndex = 0;
ev.AttendeeEmail = "person1@example.com";
ev.AttendeeDisplayName = "Person 1";
ev.AttendeeIndex = 1;
ev.AttendeeEmail = "person2@example.com";
ev.AttendeeOptional = true;

// Send an email reminder 15 minutes before the event, instead of the default reminders.
ev.ReminderUseDefault = false;
ev.RemindersOverridesCount = 1;
ev.RemindersOverrideIndex = 0;
ev.RemindersOverrideMethod = TGCRemindersOverrideMethods.gcrmEmail;
ev.RemindersOverrideMinutes = 15;

gcal.UpdateEvent(0);

To retrieve a single event, call GetEvent with the IDs of the calendar and the event. The event is added at the beginning of the Events collection, replacing any copy of it that is already in the collection.

gcal.GetEvent(calendarId, eventId);
GCalEvent ev = gcal.Events[0];
Console.WriteLine(ev.Summary + ": " + ev.StartDateTime);

// Print the email address and response of each attendee.
for (int i = 0; i < ev.AttendeesCount; i++)
{
  ev.AttendeeIndex = i;
  Console.WriteLine(ev.AttendeeEmail + ": " + ev.AttendeeResponseStatus);
}

To delete an event, call DeleteEvent with the IDs of the calendar and the event:

// Delete all events with "Canceled" in their summary.
gcal.ListEvents(calendarId, "", "");
for (int i = 0; i < gcal.Events.Count; i++)
{
  if (gcal.Events[i].Summary.Contains("Canceled"))
  {
    gcal.DeleteEvent(calendarId, gcal.Events[i].Id);
  }
}

Office365Calendars

By default, Office365Calendars manages the calendars of the signed-in user. To manage the calendars of another user (e.g., when using an application that has been granted permissions by an administrator), set the UserId configuration setting to the ID or user principal name of that user.

Calendars

To list the calendars of the user, call ListCalendars. Each calendar in the Calendars collection includes fields such as Id, Name, Color, IsDefaultCalendar, and CanEdit.

// Create a calendar, and then change its color.
office365.CreateCalendar("Team Calendar");
office365.Calendars[0].Color = TOfficeColors.occLightGreen;
office365.UpdateCalendar(0);
string calendarId = office365.Calendars[0].Id;

To delete a calendar, call DeleteCalendar with its ID:

// Delete the calendar named "Old Calendar".
office365.ListCalendars();
for (int i = 0; i < office365.Calendars.Count; i++)
{
  if (office365.Calendars[i].Name == "Old Calendar")
  {
    office365.DeleteCalendar(office365.Calendars[i].Id);
    break;
  }
}

Events

To list the events in a calendar, call ListEvents with the ID of the calendar, or an empty string for the default calendar of the user. The second and third parameters can be used to filter the events by time, or can be empty strings to list all events.

// List all events in the default calendar, across all pages.
do
{
  office365.ListEvents("", "", "");
} while (office365.ListEventsMarker.Length > 0);

foreach (OCalEvent ev in office365.Events)
{
  Console.WriteLine(ev.Subject + ": " + ev.StartDateTime + " - " + ev.EndDateTime);
}

To list the events in a time range, the GetCalendarView method can be used instead. Unlike ListEvents, which returns a single item for each series of recurring events, GetCalendarView returns each occurrence of a recurring event in the range as a separate event. The start and end times are in the format yyyy-MM-ddTHH:mm:ss.

// List the events in the default calendar in December 2026, including each occurrence of recurring events.
office365.GetCalendarView("", "2026-12-01T00:00:00", "2027-01-01T00:00:00");

To create an event, call CreateEvent with its subject, start time, end time, and calendar ID (or an empty string for the default calendar). The times are in UTC, in the format yyyy-MM-ddTHH:mm:ss. Attendees can then be set on the new event in the same way as in GoogleCalendars, before calling UpdateEvent.

office365.CreateEvent("Project Review", "2026-12-12T16:00:00", "2026-12-12T17:00:00", calendarId);
OCalEvent ev = office365.Events[0];
ev.Body = "Quarterly review of the project.";

// Add a required and an optional attendee.
ev.AttendeesCount = 2;
ev.AttendeeIndex = 0;
ev.AttendeeEmail = "person1@example.com";
ev.AttendeeType = TOCAttendeeTypes.ocatRequired;
ev.AttendeeIndex = 1;
ev.AttendeeEmail = "person2@example.com";
ev.AttendeeType = TOCAttendeeTypes.ocatOptional;

// Show a reminder 15 minutes before the event.
ev.IsReminderOn = true;
ev.ReminderMinutesBeforeStart = 15;

office365.UpdateEvent(0);

To retrieve a single event, call GetEvent with the ID of the event. The event is added at the beginning of the Events collection, replacing any copy of it that is already in the collection. To delete an event, call DeleteEvent with the ID of the event.

office365.GetEvent(eventId);
OCalEvent ev = office365.Events[0];
Console.WriteLine(ev.Subject + ": " + ev.StartDateTime + " (" + ev.ShowAs + ")");

// Delete the event if it was canceled.
if (ev.IsCancelled)
{
  office365.DeleteEvent(ev.Id);
}

Attachments

To add a file to an event as an attachment, call AddAttachment with the ID of the event, the name of the attachment, and the path of the file. Files larger than 2 MB are uploaded in fragments automatically, and the maximum size of an attachment is 150 MB.

office365.AddAttachment(eventId, "agenda.pdf", "C:\\temp\\agenda.pdf");

To list the attachments of an event, call ListAttachments, which populates the Attachments collection and fires the AttachmentList event for each attachment. To download an attachment, call RetrieveAttachment with the IDs of the event and the attachment, and the attachment is then added at the beginning of the Attachments collection, with its content in the Data field. To delete an attachment, call DeleteAttachment with the IDs of the event and the attachment.

office365.ListAttachments(eventId);
foreach (OCalAttachment attachment in office365.Attachments)
{
  Console.WriteLine(attachment.Name + " (" + attachment.Size + " bytes)");
}

// Download the first attachment and save it to a file.
office365.RetrieveAttachment(eventId, office365.Attachments[0].Id);
File.WriteAllBytes("C:\\temp\\" + office365.Attachments[0].Name, office365.Attachments[0].DataB);

Custom Fields and Requests

The calendar and event types include the most commonly used fields of each service. Every event also includes the full JSON that was returned by the service in its JSON field, and the GetEventField and SetEventField methods can be used to read and write any field of the JSON, using the index of the event in the Events collection and an XPath to the field. GetEventField returns the value as JSON (e.g., string values include quotes). The last parameter of SetEventField specifies the type of the value: 0 (Object), 1 (Array), 2 (String), 3 (Number), 4 (Bool), 5 (Null), or 6 (Raw).

// Read the status of an event.
gcal.GetEvent(calendarId, eventId);
string status = gcal.GetEventField(0, "/json/status");

// Prevent guests from modifying the event, using a field that the event type does not include.
gcal.SetEventField(0, "/json/guestsCanModify", "false", 4);
gcal.UpdateEvent(0);

For anything the components do not support directly, the SendCustomRequest method sends a request with the specified HTTP method, URL (relative to the API base URL, or absolute), and body to the service, using the authorization of the component.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@nsoftware.com.