Friday, October 25, 2013

1.6.0-beta is available!

Hi all, happy 1.6.0-beta everyone!

We just announced a new release of the .NET client library for Google APIs as you can find in this announcement post. The blogpost contains all the release highlights, so you should take a look at it before you upgrade.

This release introduced a new Google.Apis.Auth NuGet package for making authenticated calls to Google services. It supports .NET 4 applications as well as Windows Phone, Windows Store applications and Portable Class Libraries.
For supporting ASP.NET MVC applications we also provide the Google.Apis.Auth.MVC package.

The old Google.Apis.Authentication package, which depends on DotNetOpenAuth, is now obsolete and we are not going to support this package any more.
Feel free to read more in our OAuth2 wiki page for instructions how to use this package on different Windows platforms with different OAuth2 flows.

The following lines of code present how easy it is to use a Google service from WP:

           UserCredential credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
               new FileStream("client_secrets.json", FileMode.Open, FileAccess.Read),
               new[] { DriveService.Scope.Drive },
               "user", CancellationToken.None);


           var service = new DriveService(new BaseClientService.Initializer
               {
                   HttpClientInitializer = credential,
                   ApplicationName = "WP Drive Sample Application”
               });


           // DO YOUR MAGIC HERE… Sample code could look like the following:
           var list = await service.Files.List().ExecuteAsync();

And in a Windows Store applications your code should look something like the following:

           UserCredential credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
               new Uri("ms-appx:///Assets/client_secrets.json"),
               new[] { Uri.EscapeUriString(CalendarService.Scope.Calendar) },
               "user", CancellationToken.None);

           var service = new CalendarService(new BaseClientService.Initializer
               {
                   HttpClientInitializer = credential,
                   ApplicationName = "Store sample",
               });
            
           // DO YOUR MAGIC HERE… Sample code could look like the following:
           var calendarListResource = await service.CalendarList.List().ExecuteAsync();

It looks like it's the exact same code, but of course that's our intention - having one user experience for every platform. You can imagine what sample code for .NET 4 applications would look like.

Things you should be aware of:
  1. GoogleWebAuthorizationBroker is a utility class which exists in the WP and WinRT extensions. You will get it from NuGet when you target the appropriate platform. It manages all the OAuth2 "dance" for you, including redirecting the user to Google authorization server for first login and saving the user's access token and refresh token (for future use) in a specific data store for WP or WinRT applications, etc.
  2. UserCredential, the output of the AuthorizeAsync method, implements IConfigurableHttpClientInitializer, IHttpExecuteInterceptor and IHttpUnsuccessfulResponseHandler. It implements the initializer so it will be able to add itself as an unsuccessful response handler (for refreshing the token on 401 responses) and as an execute interceptor (to add the authorization header for every request). Read more here.
  3. Plugging this OAuth2 solution into your service is done by adding the UserCredential as HttpClientInitializer. That's all!

Indian Summer, Upstate NY 2013














Happy 1.6.0-beta!

Happy Halloween!

Enjoy,


Eyal

Tuesday, October 15, 2013

ApplyAuthenticationToRequest errors

In the last months, just a few weeks after releasing 1.4.0-beta version of the Google APIs client library for .NET, I was asked by several developers about the following error:
System.TypeLoadException: Method 'ApplyAuthenticationToRequest' in type 'Google.Apis.Authentication.OAuth2.OAuth2Authenticator`1' from assembly 'Google.Apis.Authentication.OAuth2, Version=1.4.0.28223, Culture=neutral, PublicKeyToken=null' does not have an implementation.

This error also occurred after releasing 1.5.0-beta (Version=1.5.0.28991). The most problematic issue was that I didn't succeed in reproducing it on my machine and I spent a lot of time trying to figure out what is the exact problem ("But It works ON MY MACHINE!").

I understood then that the real problem wasn't our implementation of ApplyAuthenticationToRequest, but was based on the usage of System.Net assembly, in particular on the parameter to ApplyAuthenticationToRequest - System.Net.HttpWebRequest.
In addition, other developers also complained about the following compilation warnings:
warning CS1684: Reference to type 'System.Net.HttpWebRequest' claims it is defined in 'c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\System.Net.dll', but it could not be found
warning CS1684: Reference to type 'System.Net.WebResponse' claims it is defined in 'c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\System.Net.dll', but it could not be found
warning CS1684: Reference to type 'System.Net.WebRequest' claims it is defined in 'c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\System.Net.dll', but it could not be found

So... I investigated and investigated and had several different directions - does it depend on the Windows platform (Vista, Windows 7 and Windows 8), what is the different in the GAC content, etc.

To make a long story short, just lately we found out the core of all evil.
Users who encounter this error should install KB2468871 patch for the .NET framework 4. This patch includes a new version of System.Net.dll (and other core assemblies as well) and it solves this issue.

Special thanks to the owners of Microsoft.Net.Http package which helped a lot in investigating this issue and refer me to this article, and specifically to the following section:
If you target the .NET Framework 4 or later, the computer must have the .NET Framework 4 with an update, Update 4.0.3 for the .NET Framework 4, or the .NET Framework 4.5 installed.

Thanks also to our developers for reporting the issue, for collecting all the data I asked them to, and for offering solutions.


Nahal Mishmar, April 2013, Israel

Eyal

Saturday, September 21, 2013

BaseClientService parameters

All Google API services inherit from BaseClientService. This class and ClientServiceRequest contain the main logic of all API calls no matter which API it is (Translate, Drive, Storage, Analytics, etc.).
BaseClientService is a thread-safe base service class and its initializer contains several properties which can change the default behavior. In this blogpost I'll go through the different properties, their default values and how you can set them differently.

I miss you Thailand!

Let's start:

HttpClientFactory
/// <summary>
/// Gets or sets the factory for creating HttpClient instance. If this
/// property is not set, the service uses a new HttpClientFactory instance.
/// </summary>
public IHttpClientFactory HttpClientFactory { get; set; }

Our recommendation is to leave this property with its default value which is null. As a result, a new HttpClientFactory will be created automatically for you. Two reason why you may consider to set this property:
1. You want to create a single ConfigurableHttpClient instance and share it with more than one service. In that case you may want to cache the created ConfigurableHttpClient. A potential solution may look like this:

public class SingleInstanceHttpClientFactory : IHttpClientFactory
   {
       private ConfigurableHttpClient configurableHttpClient;
       private object lockObject = new object();


       public ConfigurableHttpClient CreateHttpClient(CreateHttpClientArgs args)
       {
           if (configurableHttpClient == null)
           {
               lock (lockObject)
               {
                   // double lock
                   if (configurableHttpClient == null)
                   {
                       configurableHttpClient = new HttpClientFactory().CreateHttpClient(args);
                   }
               }
           }
           return configurableHttpClient;
       }
   }

2. You want to create or configure the ConfigurableHttpClient differently. Take a look in our MockHttpClientFactory for an example of Mocking the factory. In that implementation the factory doesn't create HttpClientHandler (which is the component that actually creates the wire calls, and uses HttpWebResponse and HttpWebRequest internally).

HttpClientInitializer
/// <summary>
/// Gets or sets an HTTP client initializer which is able to customize properties on ConfigurableHttpClient 
/// and ConfigurableMessageHandler.
/// </summary>
public IConfigurableHttpClientInitializer HttpClientInitializer { get; set; }

This property allow you to customize the behavior of the ConfigurableHttpClient. if you want to set different properties in ConfigurableHttpClient, like NumTries, or even common HttpClient properties like Timeout or DefaultRequestHeaders you can do so with your implementation of IConfigurableHttpClientInitializer interface.. 
The following initializer is a simple implementation that changes the timeout to 10 seconds and NumTries to 5 maximum tries for each HTTP request:

public class MyInitializer : IConfigurableHttpClientInitializer
   {
       public void Initialize(ConfigurableHttpClient httpClient)
       {
           httpClient.Timeout = TimeSpan.FromSeconds(10);
httpClient.MessageHandler.NumTries = 5;
       }
   }

Another future usage (in the future 1.6.0-beta release) is to implement a Credential class as IConfigurableHttpClientInitializer. It will add itself to the list of interceptors for adding the "Authorization" header to a HTTP request, and also to the unsuccessful response handlers list to refresh the token in case we got 401 (Unauthorized response).

DefaultExponentialBackOffPolicy
/// <summary>
/// Get or sets the exponential back-off policy used by the service. Default value is
/// <c>UnsuccessfulResponse503</c>, which means that exponential back-off is used on 503 abnormal HTTP
/// response.
/// If the value is set to <c>None</c>, no exponential back-off policy is used, and it's up to user to
/// configure the ConfigurableMessageHandler using IConfigurableHttpClientInitializer to set a specific 
/// back-off implementation (using BackOffHandler).
/// </summary>
public ExponentialBackOffPolicy DefaultExponentialBackOffPolicy { get; set; }

Exponential back-off is enabled by default to retry 503 responses. If you want to implement your own back-off policy you can change this value to None and create your own implementation of back-off. Here is a sample code for doing so:


/// Creating the client service initializer with none exponential back-off policy and set the initializer
/// to my back-off initializer implementation.
   var initializer = new BaseClientService.Initializer()
   {
       ApplicationName = "My Back-off sample",
       DefaultExponentialBackOffPolicy = ExponentialBackOffPolicy.None,
       HttpClientInitializer = new MyBackOffInitializer()
   };
   var service = new BooksService(initializer);


   public class MyBackOffInitializer : IConfigurableHttpClientInitializer
   {
       /// <summary>
       /// My fixed back-off sample implementation. It returns a given fixed number of seconds for 
/// each retry and it will keep retrying for no more than 20 times. Note that the number of tries
/// is honored also by <seealso cref="ConfigurableMessageHandler.NumTries"/>. As a result
/// there are going to be no more than 
/// min(<seealso cref="ConfigurableMessageHandler.NumTries"/>, 
/// <see cref="MaxNumOfRetries"/>+1) tries.
       /// </summary>
       public class MyFixedBackOff : IBackOff
       {
           private readonly int seconds;
           public MyFixedBackOff(int seconds)
           {
               this.seconds = seconds;
           }


           public TimeSpan GetNextBackOff(int currentRetry)
           {
               return TimeSpan.FromSeconds(seconds);
           }


           public int MaxNumOfRetries
           {
               get { return 20; }
           }
       }


       public void Initialize(ConfigurableHttpClient httpClient)
       {
           /// Create a back-off handler with the new fixed back-off logic.
           var backOffHandler = new BackOffHandler(new MyFixedBackOff(2));
           /// Add the back-off handler as unsuccessful response handler.
           httpClient.MessageHandler.UnsuccessfulResponseHandlers.Add(backOffHandler);
       }
   }

You can also consider implementing the Initialzie method as following, and back-off for each 5xx response.


       public void Initialize(ConfigurableHttpClient httpClient)
       {
           /// Create a back-off handler with the new fixed back-off logic, and retry for every 
/// 5xx response.
           var backOffHandler = new BackOffHandler(new BackOffHandler.Initializer(new MyFixedBackOff(2))
               {
/// Support exponential back-off for each 5xx request.
                   HandleUnsuccessfulResponseFunc = (resp) => (int)resp.StatusCode > 500
               });


           /// Add the back-off handler as unsuccessful response handler.
           httpClient.MessageHandler.UnsuccessfulResponseHandlers.Add(backOffHandler);
       }

Take a look at our HttpBackOffHandler and IBackOff classes for more information.

GZipEnabled
/// <summary>Gets or sets whether this service supports GZip. Default value is <c>true</c>.</summary>
public bool GZipEnabled { get; set; }

Simple property to define if this client service instance will use the GZipStream (Currently we use GZipStream from the Zlib.Portable package).

ISerializer
/// <summary>
/// Gets and Sets the Serializer. Default value is NewtonsoftJsonSerializer.
/// </summary>
public ISerializer Serializer { get; set; }

Defines the serializer we use to serialize requests and deserialize responses. Currently we support only JSON serializer, but in the future we want to target more data formats.
ISerializer supports both serialize and deserialize methods and a Format property which is used as the media type ("application/" + Format).

ApiKey
/// <summary> Gets or sets the API Key. Default value is <c>null</c>. </summary>
public string ApiKey { get; set; }

You should set this value when calling an API which doesn't access private data (e.g. Translate API). This key is used to authenticate your application for accounting purposes. More documentation is available here.  
In API Console, after you create a new project and enable a specific API (using the Services tab), the API Key will be available for you in the API Access tab as following:




IAuthenticator
/// <summary>
/// Gets or sets the Authenticator. Default value is NullAuthenticator.Instance.
/// </summary>
public IAuthenticator Authenticator { get; set; }

Note: This property is going to be obsolete from the next version (1.6.0-beta) and it's going to be deleted in version 1.7.0-beta.
IAuthenticator is our current implementation of OAuth2, which we are going to change completely. In the next release we are going to provide a new Google.Apis.Auth NuGet package which will target .NET 4 applications, Windows Phone 8, Windows store apps and PCL!
The current implementation uses IAuthenticator to apply the Authorization header to a service request. From version 1.6.0-beta we will introduce authorization code flow, user's credential and other components. That's a great idea for my next blogpost :)

ApplicationName
/// <summary>
/// Gets or sets Application name to be used in the User-Agent header. Default value is <c>null</c>.
/// </summary>
public string ApplicationName { get; set; }

Base practice is to set this property to your application name. In old versions of the library, if this property was left empty, the library extracted the name from the assembly using reflection. That's not available for us anymore since this solution isn't PCL, so it is highly recommended that you set it manually.

As you can see, you have so many different options to set the different parameters when you construct a new service. We try to provide the best default values so you won't need to customize the default behavior, but if you wish to do so, everything is doable :)