In Windows 8.1 we've enabled the ability for any Windows Store App to create appointments and add them to the user's calendar, update that appointment by replacing it on the user's calendar and the ability to remove those appointments that they've created through the AppointmentManager and AppointmentsProvider APIs.

Appointments Providers are apps that declare to be capable of handling requests from other apps to perform this addition, replacement and removal of appointments for the user and any calendar app can and should implement this functionally. For this overview of the Appointments Provider side of the equation, I'm going to start with the Appointments API sample available on MSDN and turn it into an appointments provider app to demonstrate how to declare yourself as a provider and how to handle being activated by the AppointmentManager APIs.

What you're going to need to get started:

1. You're going to need Windows 8.1 and Visual Studio 2013.
2. Familiarize yourself with Activation in Windows 8. (JavaScript, C#/C++).
3. Download the Appointments API sample in your favorite language from msdn: https://code.msdn.microsoft.com/windowsapps/Appointments-API-sample-2b55c76e (I'm going to be using C# in this post if you intend on just copying and pasting your way through the tutorial).
4. Take a look at the AppointmentManager APIs which are used by Windows Store apps to launch an Appointments Provider (your calendar app) to manage their Appointments.
5. Check out the Appointment Properties that your calendar app should support as a good Windows citizen.
6. Read over the AppointmentsProvider namespace since these are the primary types you'll be dealing with when implementing your appointments provider functionality.

Step 1: Registering your app as an Appointments Provider

In order to let Windows know that your app is capable of managing Appointments you need to update your app's manifest to include the AppointmentsProvider extension. You may have noticed though that it's not as straight forward as the existing "Declarations" when viewing the package.appxmanifest for your project. Being an Appointments Provider takes a lot of responsibility because an end user can only have one registered at a time so this is a bit of a hidden extension to keep it from being something every app feels like they should implement. The way to do go about it is to manually edit your manifest file as so:

1. Right click on "Package.appxmanifest" in your solution and select "View Code"

2. Make sure your manifest has the Windows 8.1 schema declared:

<Package xmlns="https://schemas.microsoft.com/appx/2010/manifest"
         xmlns:m2="https://schemas.microsoft.com/appx/2013/manifest">

3. Under the Application tag, register the AppointmentsProvider extension.

<Extensions>
  <m2:Extension Category="windows.appointmentsProvider">
    <m2:AppointmentsProvider>
      <m2:AppointmentsProviderLaunchActions>
        <m2:LaunchAction Verb="addAppointment" Executable="Appointments.exe" EntryPoint="Appointments.App"/>
        <m2:LaunchAction Verb="replaceAppointment" Executable="Appointments.exe" EntryPoint="Appointments.App"/>
        <m2:LaunchAction Verb="removeAppointment" Executable="Appointments.exe" EntryPoint="Appointments.App"/>
        <m2:LaunchAction Verb="showTimeFrame" Executable="Appointments.exe" EntryPoint="Appointments.App"/>
      </m2:AppointmentsProviderLaunchActions>
    </m2:AppointmentsProvider>
  </m2:Extension>
</Extensions>

NOTE: In JavaScript/HTML5 apps you'll need to provide a StartPage rather than an entry point, e.g. <m2:LaunchAction Verb="removeAppointment" StartPage="removeAppointment.html" />

At this point we've told the system that our app is an appointments provider and if you build and run your project you should notice in the PC Settings app under "Search and apps" -> "Defaults" your app should be an option under "Calendar"

Step 2: Handling the AppointmentsProvider activation kind

Being an appointments provider means that your app must handle each of the four appointments provider "Verbs" which stand for the various actions an appointments provider can perform for other apps, those include Add, Remove and Replace an Appointment and ShowTimeFrame, which is basically just activating the appointments provider app to show the user's calendar at a particular date and time. You can determine which verb you were activated for by querying for IAppointmentsProviderActivatedEventArgs and inspecting the Verb property. You can use the AppointmentsProviderLaunchActionVerbs statics class to help in the comparison.

Here's an example of the OnActivated handler:

protected override void OnActivated(IActivatedEventArgs args)
{
    if (args.Kind == ActivationKind.AppointmentsProvider)
    {
        IAppointmentsProviderActivatedEventArgs providerArgs = args as IAppointmentsProviderActivatedEventArgs;
        if (providerArgs.Verb.Equals(AppointmentsProviderLaunchActionVerbs.AddAppointment))
        {

        }
        else if (providerArgs.Verb.Equals(AppointmentsProviderLaunchActionVerbs.RemoveAppointment))
        {

        }
        else if (providerArgs.Verb.Equals(AppointmentsProviderLaunchActionVerbs.ReplaceAppointment))
        {

        }
        else if (providerArgs.Verb.Equals(AppointmentsProviderLaunchActionVerbs.ShowTimeFrame))
        {

        }
    }
}

Now if you set a break point on the OnActivated function and run the sample, you can test the various scenarios and watch your app get activated for each verb. Here's a screenshot of a new instance of the sample app being activated for the Add Appointment verb at the splash screen:

TIP: I strongly recommend using the VS Simulator when debugging Appointments Providers considering the Appointments Provider is launched in a hosted flyout style window. The hosted window is dismissed any time the user clicks or touches outside of the window.

Step 3: Dealing with appointment operations

Now you're app is registered properly and being activated for each of the appointments provider launch action verbs. This is where your part comes to play, you have to add the logic to add, remove, or replace the appointment that the other app wants and report status back. The add, remove and replace arguments each have an Operation member that your app will use to manage the lifetime of that appointment operation. The basic flow is this:

• Once you know which verb you were activated for, cast the IAppointmentsProviderActivatedEventArgs to the appropriate type: AppointmentsProviderAddAppointmentActivatedEventArgs, AppointmentsProviderRemoveAppointmentActivatedEventArgs, AppointmentsProviderReplaceAppointmentActivatedEventArgs, or AppointmentsProviderShowTimeFrameActivatedEventArgs.
• Update your UI with the appropriate information based on the information given to you on the event args. For example, you may want to show the appointment information with a confirmation button for Add Appointment using the AddAppointmentOperation.AppointmentInformation member.
• Once the user clicks your "Okay" button to confirm the add, remove or replace then you want to dismiss the flyout your app is hosted in so that you can process the request without the user having to wait on it. Each operation type has this DismissUI method that will hide your flyout and indicate to Windows that you're finished with user interaction.
• When you've finished actually doing the work in the background to save or remove the appointment then you should call the appropriate ReportCompleted method on the operation member.

Add Appointment Example

AppointmentsProviderAddAppointmentActivatedEventArgs addArgs = args as AppointmentsProviderAddAppointmentActivatedEventArgs;
var appointmentToAdd = addArgs.AddAppointmentOperation.AppointmentInformation;

// Show UI with this appointment information populated, maybe allow the user to edit some of the properties before saving.

// When the user clicks "Okay" call DismissUI to tell Windows you're done with user interaction
addArgs.AddAppointmentOperation.DismissUI();

// Do work in the background to save the results and then call report completed with a generated globaly unique appointment id
addArgs.AddAppointmentOperation.ReportCompleted("Appointment Id");

Remove Appointment Example

AppointmentsProviderRemoveAppointmentActivatedEventArgs removeArgs = args as AppointmentsProviderRemoveAppointmentActivatedEventArgs;
var appointmentIdOfAppointmentToRemove = removeArgs.RemoveAppointmentOperation.AppointmentId;

// Look up the appointment and determine whether or not to remove the entire series or just an instance
Appointment appointmentToRemove = GetAppointmentFromDatabase(appointmentIdOfAppointmentToRemove);
if (appointmentToRemove.Recurrence != null)
{
    // If this appointment has recurrence, the instanceStartDate property on RemoveAppointmentOperation tells you which instance to remove
    DateTimeOffset instanceDateToRemove = removeArgs.RemoveAppointmentOperation.InstanceStartDate.Value;
}

// Populate UI and ask the user to confirm the removal

// When the user clicks "Okay" call DismissUI to tell Windows you're done with user interaction
removeArgs.RemoveAppointmentOperation.DismissUI();

// When you've finished removing the appointment from your app data, call ReportCompleted to tell the calling app that it was removed
// If the appointment couldn't be found then you should still call ReportCompleted
removeArgs.RemoveAppointmentOperation.ReportCompleted();

NOTE: The ShowTimeFrame verb activates you in a standard main window split 50/50 along with the calling app. There are no special lifetime considerations for ShowTimeFrame like there are for Add, Replace and Remove since you're not being activated in a hosted flyout. Just take the TimeToShow and Duration properties on the AppointmentsProviderShowTimeFrameActivatedEventArgs and display a nice view of the user's calendar around that time.

TIP: The flyout dimensions are fixed at 320px by 400px so be very careful when crafting your UI for the Add, Remove and Replace operations.

I could go into a lot more details about how to tailor your app to become an amazing calendar replacement through the use of the new Appointments Provider APIs in Windows 8.1 but think that this quick tutorial should give you enough to get started. Please leave any specific questions you may have in the comments section and I'll be happy to address them. Happy coding!

-Nick

I've been using Windows Phone 8 on my Nokia Lumia 928 for the past several months and have had such an amazing experience so far that I felt the need to share. First, a little background into my digital life, before I jumped on to a Windows Phone, I was an avid iPhone user having both the iPhone 4 and 5 over the two to three years and before that I had the Motorola Droid. As a Microsoft employee, I felt obligated to switch to a Windows device but was afraid that I would miss the apps and the thin and light form factor of the iPhone which kept me from switching for quite a while. I say that just to prove that I'm not just some 'fanboy' ranting on about how awesome this operating system is without the experience to prove it, it was actually a hard choice for me to make the switch but I'm very glad that I did and won't look back.

Throughout the past year I have started working more closely with the Windows Phone team and was able to see first hand how passionate and excited they are about their product which made me finally make the leap of faith and purchase a Nokia 928 back in June. The minute I took it out of the box I was little disappointed with the heft of the device and browsing through the store took me back to early days of Android 2.0 a bit when I didn't find all the hundreds of apps that I had installed on my iPhone (the vast majority of which I didn't use, I quickly learned). Those feelings were overcome once I connected my Microsoft Account and saw how alive my phone became and aside from the difficulty in reaching the back button when using the device with one hand, I do appreciate the greater screen real estate. I'm heavily invested in the Mircrosoft ecosystem so it was nice to see all my emails, pictures, skydrive documents, one note notebooks, music (through Xbox Music pass), Xbox achievements, and contacts show up and immediately starting to appear on my start screen. Interacting with the OS felt modern, a breath of fresh air. This may sound like a denouncement but I swear its a huge compliment - the first reaction I had once everything was set up was to call my parents and tell them that I had finally found the smart phone for them (they both ended up buying one and absolutely love their phones, probably more than I do).

The experience only got better over the next couple months as I got more familiar with the platform and how intuitive everything was. I could actually personalize my phone by choosing which tiles/apps I value and what sizes I want them on the start screen which is a lot nicer than just being able to move icons around and throwing them into folders. I realized how little I actually enjoyed using my phone when I used an iPhone as my daily driver, this one felt alive and personal. This OS is not just a bunch of jumping back and forth into and out of individual silos of apps, with Windows Phone everything is connected and seamlessly flows from one experience to the next and back. The introduction of the Bing News, Weather, Finance, and Sports apps made the experience all the better and with Nokia's additions like Glance and double tap to wake, I can honestly say that I love my phone.

My Start Screen, the essential apps

This is my start screen which I use to hold all the apps that I use pretty much every day. It's very nice to be able to see updates at a glance on the live tiles; I check the weather without ever opening an app, I can see how much money I've lost or gained throughout the day with a quick glance at the stock tile, I see photos and status updates from my family with the Family pin from the People Hub, I can book my connector ride to work at a moments notice, or check the traffic over Lake Washington to see how much longer I should stay at the office... or sleep in. I have all of my communication apps together near the top so that I can see the number of calls, emails, texts, or lync messages that I've missed. The music tile shows the artist that's playing if I'm listening to music, and my calendar actually tells me where I need to go next. These are really all the apps that I really need and rarely to I find myself going to the store to hunt down something that's missing.

The good, and bad.

Here is a quick list the things that I absolutely love about my Windows Phone, and the things that could use some improvement.

The Good:

• The tiles are far more useful than I anticipated, sometimes I find myself turning on my screen just to stare at them jump around.
• On Nokia devices, the glance and double tap to wake on GDR2/Amber is awesome!
• Bing images as your lock screen background brings a fresh face to the phone every day.
• While driving, texting via Bluetooth is extremely good, a voice will ask if you want it read aloud or ignore, and then you can respond or not.
• Having Office is very handy, especially when it comes to SharePoint and right's protected documents.
• Email is world class unlike every other platform out there.
• Facebook messaging within the first party standard texting/messaging app is extremely nice.
• Being able to link various sets of mailboxes is a nice feature rather than the all or nothing "universal mailbox" found on other platforms.
• Earning achievements in games is nice.
• The back button and backstack is awesome, it really connects the app to app experience. I especially like that many apps will rely on this for navigating to web content via IE rather than hosting their own webviews. 
• Xbox Music is unmatched.

The Bad (for now):

• I miss notification toasts a lot (especially on football days where ESPN alerts happen frequently).
• I can't close an app without restarting the phone, I know that in most circumstances you don't have to but there is a need every once and a while. (Update: GDR3 fixes this! https://blogs.windows.com/windows_phone/b/windowsphone/archive/2013/10/14/announcing-our-third-windows-phone-8-update-plus-a-new-developer-preview-program.aspx)
• No SnapChat, this is one of those apps that's preventing my younger brother from getting a Windows Phone. (This bullet can also be repurposed for any apps falling into the "App Gap" territory)
• Podcasts from the Store/Music hub take way too long to become available, fortunately other apps like i Podcast, excel at this.
• Quick access to airplane mode or wifi and Bluetooth toggles would be extremely helpful.
• The call and SMS filter doesn't seem to work for me.
• Internet Explorer drop downs could use some work, these worked a lot better on Safari.

I'm sure these lists will change over time as the platform matures and evolves. In general though, Windows Phone 8 is an amazing platform and I'm getting tired of tech bloggers and journalists not giving it the time of day or spreading mis-information about it for lack of actually ever trying it. It is the only platform that I would recommend to newcomers to the smart phone market for it's ease of use and "all-in-one" package of Microsoft services that get better all the time, and one that I strongly urge people who are diehard Android or iOS fans to try for an extended period of time, I think they'd be surprised how quickly they'll fall in love.

I've been meaning to get into blogging for a while now and thought a post on my experiences with Windows Phone would be a good place to start. I have another post in the works about some of the work I did in Windows 8.1 which I'll probably put up in a week or so covering the new Appointments APIs and how to actually write an Appointments Provider app. Apparently some one already beat me to it on how to use the APIs themselves, even though they completely stole my sample code... :) - https://www.codeguru.com/win_mobile/win_store_apps/programmatically-creating-and-updating-appointments-in-windows-8.1.htm. In the mean time I can be found on Twitter, @naeubanks.

-Nick