search

jfversluis / Plugin.Maui.CalendarStore

Plugin.Maui.CalendarStore provides the ability to access the device calendar information in your .NET MAUI application.
MIT License
79 stars 12 forks source link
android calendar dotnet dotnet-maui hacktoberfest ios macos maui windows

readme

Plugin.Maui.CalendarStore

Plugin.Maui.CalendarStore provides the ability to access the device calendar information in your .NET MAUI application.

Install Plugin

NuGet

Available on NuGet.

Install with the dotnet CLI: dotnet add package Plugin.Maui.CalendarStore, or through the NuGet Package Manager in Visual Studio.

API Usage

Plugin.Maui.CalendarStore provides the CalendarStore class that has methods to retrieve calendars, events and attendee information from the device's calendar store.

You can either use it as a static class, e.g.: CalendarStore.Default.GetCalendars() or with dependency injection: builder.Services.AddSingleton<ICalendarStore>(CalendarStore.Default);

Permissions

Before you can start using CalendarStore, you will need to request the proper permissions on each platform.

The runtime permission is automatically requested by the plugin when any of the methods is called.

iOS/macOS

For more information, please refer to the official Apple documentation.

iOS 17+

As of iOS 17, Apple has introduced a new layer of security for accessing calendar data. There is now a difference between only writing data to a calendar and obtain full access to calendar data. To use these, add the following keys to your info.plist file. When declared, the permission will be requested automatically at runtime.

<key>NSCalendarsWriteOnlyAccessUsageDescription</key>
<string>This app needs your permission to write events to your calendars. This includes creating events, but not reading, modifying or deleting events.</string>

<key>NSCalendarsFullAccessUsageDescription</key>
<string>This app needs your permission to fully manage events on your calendars. This includes reading, writing, modifying and deleting events.</string>

Remember, you always want to declare the least amount of permissions that are needed for your app. Else this might look suspicious to your users when you have something declared, but you're not using it. That means: leave out any key from above that is not applicable to your situation.

Additionally, make sure that the descriptions you provide are useful and describe why you want to access this data. Failing to do so might result in your app being rejected from the App Store.

If you also still want to support older iOS versions (prior to version 17), also follow the instructions below.

For a sandboxed macOS application, additionally you will have to add an entry to the Entitlements.plist, you will need to add the com.apple.security.personal-information.calendar key with a value of true.

See an example of a complete Entitlements.plist file below.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.personal-information.calendar</key>
    <true/>
</dict>
</plist>
iOS < 17

On iOS and macOS prior to iOS 17, add the NSCalendarsUsageDescription key to your info.plist file. When declared, the permission will be requested automatically at runtime.

<key>NSCalendarsUsageDescription</key>
<string>This app wants to access your calendars</string>

If your app supports older iOS versions than iOS 17, include this key as well as the ones described above.

Android

On Android declare the READ_CALENDAR permission in your AndroidManifest.xml file for reading calendar information. If you also want to write information, also add the WRITE_CALENDAR permission.

This should be placed in the manifest node. You can also add this through the visual editor in Visual Studio.

The runtime permission is automatically requested by the plugin when any of the methods is called.

<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />

Windows

On Windows declare the Appointments permission in your Package.appxmanifest file.

This should be places in the <Capabilities> node, that is under the <Package> node.

The runtime permission is automatically requested by the plugin when any of the methods is called.

<uap:Capability Name="appointments"/>

Dependency Injection

You will first need to register the Calendars with the MauiAppBuilder following the same pattern that the .NET MAUI Essentials libraries follow.

builder.Services.AddSingleton(CalendarStore.Default);

You can then enable your classes to depend on ICalendarStore as per the following example.

public class CalendarsViewModel
{
    readonly ICalendarStore calendarStore;

    public CalendarsViewModel(ICalendarStore calendarStore)
    {
        this.calendarStore = calendarStore;
    }

    public async Task ReadCalendars()
    {
        var calendars = await calendarStore.GetCalendars();

        foreach (var c in calendars)
        {
            Console.WriteLine(c.Name);
        }
    }
}

Straight usage

Alternatively if you want to skip using the dependency injection approach you can use the Calendars.Default property.

public class CalendarsViewModel
{
    public async Task ReadCalendars()
    {
        var calendars = await CalendarStore.Default.GetCalendars();

        foreach (var c in calendars)
        {
            Console.WriteLine(c.Name);
        }
    }
}

CalendarStore

Once you have created a CalendarStore instance you can interact with it in the following ways:

Methods

IEnumerable<Calendars> GetCalendars()

Retrieves all available calendars from the device.

Calendar GetCalendar(string calendarId)

Retrieves a specific calendar from the device.

string CreateCalendar(string name, Color? color = null)

Creates a new calendar on the device with the specified name and optionally color. Returns the ID of the newly created calendar.

UpdateCalendar(string calendarId, string newName, Color? newColor = null)

Updates the calendar, specified by the unique identifier, with the given values.

IEnumerable<CalendarEvent> GetEvents(string? calendarId = null, DateTimeOffset? startDate = null, DateTimeOffset? endDate = null)

Retrieves events from a specific calendar or all calendars from the device.

CalendarEvent GetEvent(string eventId)

Retrieves a specific event from the calendar store on the device.

string CreateEvent(string calendarId, string title, string description, string location, DateTimeOffset startDateTime, DateTimeOffset endDateTime, bool isAllDay = false)

Creates an event in the specified calendar with the provided information. Returns the ID of the newly created event.

string CreateEvent(CalendarEvent calendarEvent)

Creates an event based on the information in the CalendarEvent object. This is basically just a convenience method that calls CreateEvent with all the unpacked information from calendarEvent. Returns the ID of the newly created event.

string CreateAllDayEvent(string calendarId, string title, string description, string location, DateTimeOffset startDate, DateTimeOffset endDate)

Creates an all-day event in the specified calendar with the provided information. This is basically just a convenience method that calls CreateEvent with isAllDay set to true. Returns the ID of the newly created event.

UpdateEvent(string eventId, string title, string description, string location, DateTimeOffset startDateTime, DateTimeOffset endDateTime, bool isAllDay)

Updates an event, specified by the unique identifier, on the device calendar.

UpdateEvent(CalendarEvent eventToUpdate)

Updates an event on the device calendar. This is basically just a convenience method that calls UpdateEvent with all the details provided from eventToUpdate.

DeleteEvent(string eventId)

Removes an event, specified by the unique identifier, from the device calendar.

DeleteEvent(CalendarEvent eventToDelete)

Removes an event from the device calendar. This is basically just a convenience method that calls DeleteEvent with eventToDelete.Id.

Acknowledgements

This project could not have came to be without these projects and people, thank you! <3

Xamarin.Essentials PR

There are a couple of people involved in bringing this functionality to Xamarin.Essentials. Unfortunately the PR was never merged. In an attempt not to let this code go to waste, I transformed it into this library. Thank you @mattleibow, @nickrandolph, @ScottBTR and @mkieres for the initial work here!