This document describes how to use the .NET client library to send Google Data API ("GData") queries and interpret returned responses.

Google provides a set of client libraries for interacting with GData-enabled services, in a variety of programming languages. Using these libraries, you can construct GData requests, send them to a service, and receive responses.

This document provides a set of examples of common uses of the C# version of the client library, followed by other information about writing GData clients. At the end of this document is a link to the reference documentation for the C# client library, in NDoc format.

To use this client library, you need the .NET 1.1 runtime, and you should also be current on all patches.

Download the .NET client library.

This guide's examples refer to the Google Calendar API, but this guide is not an accurate or up-to-date guide to using the Calendar API. For information about using the .NET client library with a specific service's Data API, see the service-specific documentation. For example, if you're working with Calendar, read the Calendar Data API Developer's Guide.

Contents

Audience

This document is intended for C# programmers who want to write client applications that can interact with GData services.

This document assumes that you understand the general ideas behind the Google Data APIs protocol. It also assumes that you know how to program in C#.

Data model overview

The C# client library provides a set of classes that correspond to the elements and data types used by the Google Data APIs. For example, there's a Feed class, which corresponds to the <atom:feed> element; it has methods for creating an entry, getting and setting the values of various sub-elements, and so on. There's also an Entry class, which corresponds to the <atom:entry> element. Not every element defined in the Google Data APIs has its own class; for details, see the reference documentation.

The library can automatically parse Atom content and put the values of the Atom elements into appropriate objects. For example, the getFeed method gets a feed, parses it, and returns a Feed object with the resulting values.

To send a feed or entry to a service, you create a Feed or Entry object, then call a library method (such as the insert method) to automatically translate the object into XML and send it.

You can parse and/or generate XML yourself if you prefer; the easiest way to do that is with an appropriate third-party library.

Just as the Google Data API's XML syntax is extensible, the corresponding object model is extensible. For example, the client library provides classes corresponding to the elements defined in the Google Data namespace.

Tutorial and examples

The following examples show how to send various GData requests using the C# client library.

To make them more concrete, these examples show how to interact with a specific service: Google Calendar. We'll point out places where Calendar differs from other Google services, to help you adapt these examples for use with other services. For more information about Calendar, see the Google Calendar Data API documentation.

Building and running your client

To compile the examples in this document, you'll need to use the following using statement:

using Google.GData.Client;

Requesting a feed

As described in the Google Calendar Data API documentation, you can request a Calendar feed by sending the following HTTP request to Calendar:

GET http://www.google.com/calendar/feeds/userID/private/full

Of course, you have to replace userID with the user's email address; see the Calendar document for details. You can, instead, use the special default URL for interacting with Calendar (as described in the Calendar document), but in this document we'll use the private full feed URL, which contains the user ID.

You also have to provide appropriate authentication. Note that the authentication system we're using here (known as "Google Authentication for Installed Applications") is appropriate only for use in installed client applications such as desktop clients, not for use in web applications. For more information about authentication, see the Google Account Authentication documentation.

To request a Calendar feed using the C# client library, for a user with email address "jo@gmail.com" and password "mypassword", use the following code:

// Create a query and service object:

FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");

// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Tell the service to query:
AtomFeed calFeed = service.Query(query);

The Service class represents a client connection (with authentication) to a GData service. The general procedure for sending a query to a service using the client library consists of the following steps:

1. Obtain or construct the appropriate URL.
2. If you're sending data to a service (for example, if you're inserting a new entry), then transform the raw data into objects using the client library classes. (This step doesn't apply if you're just requesting a feed, as we're doing in this example.)
3. Create a new Service instance, setting the service name (such as "cl" for Calendar) and your application's name (in the form companyName-applicationName-versionID).
4. Set the appropriate credentials.
5. Call a method to send the request and receive any results.

The service.setUserCredentials method sets the service.Credentials property with a standard .NET Network credentials object. The credentials are set to the ID and password of the user on whose behalf your client is sending the query. The examples in this document use the "Authentication for Installed Applications" authentication system; for more information about other authentication systems, see the Google Account Authentication documentation.

To request an entire feed, you call the service.Query method, which takes a FeedQuery object and returns the entire feed found at that URL. We'll show how to send more specific queries later in this document.

Like other methods of the Service class, Query handles authentication and redirects as necessary.

Inserting a new item

To insert an item into a Calendar feed, you might use the following code:

AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March"; 
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth"; 
entry.Content.Content = "Meet for a quick lesson.";

Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);

After setting the URL, we construct an AtomEntry object.

The entry title is a AtomTextConstruct, a class that holds text in various forms (plain text, HTML, or XHTML). The entry content is represented by an AtomContent object, a class that can hold either plain text or other forms of content, including XML and binary data.

Each author is represented as a name, a URI, and an email address. (In this example, we're leaving out the URI.) You add an author to an entry by adding an AtomAuthor object to the entry's Authors collection.

We're using the same Service object that we created in the previous example. In this case, the method to call is Insert, which sends an item to the specified insertion URL.

The service returns the newly created entry, which may contain additional server-generated elements, such as an edit URL for the entry.

The above code is equivalent to sending POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (with proper authentication) and providing an entry.

Requesting a specific entry

The following code lets you request the specific entry that you inserted in the previous example.

In the context of this series of examples, retrieving that entry isn't really necessary, because Calendar already returned the inserted entry; but the same technique can be applied whenever you know the URL for an entry.

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

The inserted entry has a property, SelfUri, that returns an AtomUri object that, using its ToString() method, can be used to create a new URI object.

Then we just have to call the service's Query method to get a new AtomFeed object, with just one entry in its Entries collection.

The above code is equivalent to sending GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID to Calendar, with proper authentication.

Searching for an entry

To retrieve the first match in a full-text search, use the following code:

FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis"; 
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
  AtomEntry firstMatchEntry = myResultsFeed.Entries[0]; 
  String myEntryTitle = firstMatchEntry.Title.Text; 
}

This example starts by constructing a FeedQuery object, which consists mostly of a URL plus associated query parameters. Each of the standard GData query parameters has a property.

After constructing the FeedQuery, we pass it to the service's Query method, which returns a feed containing the query results. An alternative approach would be to construct a URL yourself (by appending query parameters to the feed URL) and then call the Query method, but the FeedQuery method provides a useful layer of abstraction so that you don't have to construct the URL yourself.

The feed's Entries collection returns a list of the entries in the feed; Entries.Count returns the number of entries in the feed.

In this case, if the query returned any results, we assign the first matching result to an AtomEntry object. Then we use the AtomEntry class's Title property to retrieve the entry's title.

The above code is equivalent to sending GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis to Calendar.

Querying by category

Note: Google Calendar doesn't associate labels with events, so this example doesn't work with Calendar.

To retrieve a feed consisting of all the entries that match the earlier full-text search and that are in a particular category or have a particular label, use the following code:

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

The AtomCategory class, of course, represents a category to be used in a category filter. The QueryCategory class can contain multiple categories, but in this case we're constructing a filter with only one category.

Then we add that filter to the existing query, which still contains the full-text query string from the previous example.

We again use the Query method to send the query to the service.

If Calendar allowed a category search, the above code would be equivalent to sending GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis to Calendar.

Updating an item

To update an existing item, use the following code. In the following example, we're changing the previously retrieved entry's title from its old text ("Tennis with Beth") to "Important meeting."

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

First we set a new title for the entry we fetched earlier. Then we just call the Upate method to send the updated entry to the service.

The service returns the updated entry, including a new URL for this entry's new version. (For more information on entry versions, see the Optimistic concurrency section of the v1 protocol reference document.)

The above code is roughly equivalent to sending PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID to the service, along with the new entry (in Atom format) to replace the original entry.

Deleting an item

To delete an existing item, use the following code:

updateEntry.Delete();

The URL to use for deletion is the same as the edit URL, so this example is very similar to the previous one, except of course that we're calling the Delete method instead of Update.

The above code is roughly equivalent to sending DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID to the service.

Working with Google Calendar feeds

The above examples outline how to use the Google Data C# API to work with generic GData feeds. When you're working with a Google Calendar feed in particular, though, the feed contains a lot of calendar-specific data that is not easily accessible using the standard Atom-oriented objects in the base API library. To help you interact with those feeds, we provide the following extensions:

using Google.GData.Extensions;
using Google.GData.Calendar;

The Extensions namespace deals with extensions in general; the Calendar namespace gives you access to a customized calendar service, feed and query object. You can find a more elaborate example of how those extensions are used in the /Samples subdirectory of the C# API installation. The following objects are added:

EventQuery

A subclass of FeedQuery, which allows you to set two custom parameters for the Calendar service (start-min and start-max).

CalendarService

A subclass of service, which can return an event feed.

EventFeed

A subclass of AtomFeed, exposing EventEntries.

EventEntry

A subclass of AtomEntry, which has additional properties related to calendar data.

For more details about those special classes, see the API documentation and the samples program.

Reference

For reference information about the C# client library, see the reference documentation.

Back to top