gekidoku / calendars

Cross-platform calendar API plugin for Xamarin and Windows and MAUI

Calendar API plugin for Xamarin and Windows

Cross-platform plugin for querying and modifying device calendars. Supports basic CRUD operations with calendars and events. Try it out with the Calendars Tester.

Setup & Usage

• Available on NuGet: http://www.nuget.org/packages/CClarke.Plugin.Calendars
• Install into your .NETStandard/PCL project and Client projects.
• Call CrossCalendars.Current from any project to gain access to APIs.

Supports

• Xamarin.iOS (x64 Unified)
• Xamarin.Android
• Universal Windows Platform (uap10.0 NuGet target)

Example

var calendars = await CrossCalendars.Current.GetCalendarsAsync();

// ...figure out which calendar to use, e.g. by prompting the user and considering the CanEditEvents property...

var calendarEvent = new CalendarEvent
{
   Name = "Add calendar support",
   Start = DateTime.Now,
   End = DateTime.Now.AddHours(1),
   Reminders = new List<CalendarEventReminder> { new CalendarEventReminder() }
};
await CrossCalendars.Current.AddOrUpdateEventAsync(selectedCalendar, calendarEvent);

// calendarEvent.ExternalID now contains the unique ID for the event, which can be stored and later used to retrieve the event via GetEventByIdAsync

Platform Notes:

• Android:
  • Requires ReadCalendar & WriteCalendar permissions.
  • Android calendars have additional "account name" and "owner account" properties. By default, this will set those properties for new calendars according to the application package label. However, custom names can be set via the Android implementation class.
  • Unlike iOS, permissions will not automatically be requested on Android M and above. Check out the Permissions Plugin for help with this.
• Universal Windows Platform:
  • Calendar color is read-only.
  • Requires the Appointments capability.
  • Only allows a single reminder.
• iOS:
  • (iOS 10+) Info.plist must include the NSCalendarsUsageDescription key with user-facing text that explains why your app desires calendar access. See Apple docs.
  • Calendar permission will be requested when any API function is called, if it has not already been granted.
  • The end time for all-day events will be returned as midnight of the following day (which is consistent with WinPhone/Android, but different from native iOS).

A Note on Creating Calendars:

• Android’s default Calendar app (the Google one) does not allow creating or deleting calendars. Most 3rd-party calendars do (including some provided by manufacturers)… it is not a limitation of Android itself. But it is worth being aware that it’s possible the user may not know how to later remove a calendar your app created.
• Windows does not allow 3rd-party apps to write to the default calendar. You must create an app-specific calendar in order to add events.
• iOS allows creating/deleting calendars, but it’s a bit tricky: it is very important to specify the correct “calendar source” (e.g. iCloud/Gmail/local) for the user’s device configuration (i.e. whether or not iCloud is enabled), otherwise it may be successfully created but hidden (both from the built-in calendar app and from the API). This library attempts to take care of that for you, but it is theoretically possible that it could fail.
  • Although the built-in iOS calendar app allows creating/deleting calendars, most 3rd-party calendar apps do not (quite contrary to the Android scenario). Possibly due to this complication.
• More discussion of this in Issue #10

Limitations:

• Recurring events are not currently supported.
• Meeting attendees and other custom fields are also not supported.
• Async is a lie on Android and iOS. Windows provides a native async API, so to provide a common API abstraction, the Android and iOS implementations use background threads.
• Some performance tradeoffs were made in the interest of providing a clear and consistent API across all platforms with helpful error checking. Android in particular provides certain optimizations for activities that are unavailable to a cross-platform API. However, this may still be useful to an Android app that is not constantly re-querying calendar data, or to one that is written with Xamarin.Forms.
• Does not currently provide access to the native platform UIs.

tl;dr: You probably don't want to use this to write a replacement calendar app.