Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jfversluis/plugin.maui.calendarstore
Plugin.Maui.CalendarStore provides the ability to access the device calendar information in your .NET MAUI application.
https://github.com/jfversluis/plugin.maui.calendarstore
android calendar dotnet dotnet-maui hacktoberfest ios macos maui windows
Last synced: 19 days ago
JSON representation
Plugin.Maui.CalendarStore provides the ability to access the device calendar information in your .NET MAUI application.
- Host: GitHub
- URL: https://github.com/jfversluis/plugin.maui.calendarstore
- Owner: jfversluis
- License: mit
- Created: 2023-08-22T09:20:30.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2023-12-21T13:51:05.000Z (11 months ago)
- Last Synced: 2024-05-01T15:42:07.623Z (7 months ago)
- Topics: android, calendar, dotnet, dotnet-maui, hacktoberfest, ios, macos, maui, windows
- Language: C#
- Homepage:
- Size: 8.27 MB
- Stars: 69
- Watchers: 3
- Forks: 10
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Plugin.Maui.CalendarStore
`Plugin.Maui.CalendarStore` provides the ability to access the device calendar information in your .NET MAUI application.
## Install Plugin
[](https://www.nuget.org/packages/Plugin.Maui.CalendarStore/)
Available on [NuGet](http://www.nuget.org/packages/Plugin.Maui.CalendarStore).
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(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](https://developer.apple.com/documentation/eventkit/accessing_the_event_store#2975207).
##### 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.
```xml
NSCalendarsWriteOnlyAccessUsageDescription
This app needs your permission to write events to your calendars. This includes creating events, but not reading, modifying or deleting events.
NSCalendarsFullAccessUsageDescription
This app needs your permission to fully manage events on your calendars. This includes reading, writing, modifying and deleting events.
```
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
com.apple.security.app-sandbox
com.apple.security.personal-information.calendar
```
##### 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.
```xml
NSCalendarsUsageDescription
This app wants to access your calendars
```
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.
```xml
```
#### Windows
On Windows declare the `Appointments` permission in your `Package.appxmanifest` file.
This should be places in the `` node, that is under the `` node.
The runtime permission is automatically requested by the plugin when any of the methods is called.
```xml
`````
### Dependency Injection
You will first need to register the `Calendars` with the `MauiAppBuilder` following the same pattern that the .NET MAUI Essentials libraries follow.
```csharp
builder.Services.AddSingleton(CalendarStore.Default);
```
You can then enable your classes to depend on `ICalendarStore` as per the following example.
```csharp
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.
```csharp
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 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 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](https://github.com/xamarin/Essentials/pull/1384) was never merged. In an attempt not to let this code go to waste, I transformed it into this library. Thank you [@mattleibow](https://github.com/mattleibow), [@nickrandolph](https://github.com/nickrandolph), [@ScottBTR](https://github.com/ScottBTR) and [@mkieres](https://github.com/mkieres) for the initial work here!