Demystifying The Code

PHP and IIS: Running PHP under Fast CGI and Url Rewriting

PHP Interop Series

This is part of a small series of blog posts and screencasts that I am doing on interoperability between PHP and the Microsoft stack.  My goal is to illustrate some features of the MS stack that PHP developers can take advantage of, as well as to illustrate how it is done.

Screencasts

You can see screencasts on YouTube of the topics in this post here:

Installing PHP and FastCGI on IIS7 in under 5 minutes

Create SEO-Friendly URLs with the IIS7 UrlRewrite Module

Introduction

You can run PHP (as well as other CGI apps) on IIS7 with high performance and reliability thanks to FastCGI.  CGI is a protocol that defines how web servers launch an executable resulting from a request, pass it arguments and return the dynamic response.  You have been able to host CGI applications in IIS in the past, however there have been challenges prior to FastCGI.  As it turns out, the challenge is that there are certain modules (in PHP, for instance) that are not thread safe.  For that reason, IIS traditionally spun up a new process for each request.  This provided the reliability necessary in the face of non-thread-safe modules.  However, the performance suffered due to the cost of spinning up all of these processes.  Enter FastCGI.  It guarantees that each process will handle 1 request at a time (providing the reliability), but it allows for process reuse by maintaining a pool of processes.

While installing PHP on IIS7 wasn’t overly complex in the past (see this article if you want the details) we now have the Web Platform Installer that makes installing FastCGI, PHP and much much more a breeze.  Now, just because you can host PHP on IIS with reliability and high performance, it doesn’t necessarily mean you should.  You need some reasons, right?  Well, in this post, I will illustrate how to install PHP and FastCGI on IIS7 easily and illustrate one of many reasons you will want to: The UrlRewrite Module.  This module allows you to easily create SEO-friendly Uris for your application.  Let’s get to it.

Set Up a Test Environment (optional)

You can test all of this on Vista, Windows 7 or Windows Server 2008.  We have made it pretty easy for you to to set up a virtual environment for testing.  You can click here to download Windows Server 2008 Evaluation Virtual Hard Drive Images.  Although it says Virtual Server 2005 is required, the VHD works on Virtual PC 2007, as well.  You simply need to download the WS08_RTM_x86_EnterpriseVHD.exe or, if you want smaller downloads the WS08_RTM_x86_Enterprise.part01.exe and all of the subsequent rar files.  You will also need the WS08_ServerCore86_EnterpriseVHD.exe.  You simply uncompress these and register the VHD with Virtual PC or Virtual Server.  That is exactly what I did.

Install the Web Platform Installer

1. Navigate to http://www.microsoft.com/web/downloads/platform.aspx and click the download link to ‘Microsoft Web Platform Installer 2.0 Beta’
   
2. Click Run (If you get a security warning, click run again)
   
3. The Web Platform Installer is now installed.  You will see the UI, where you can choose items to install.  Feel free to close this.  You can re-open it at any time.
   

Install PHP, FastCGI and the URLRewrite Module

1. Open the Web Platform Installer 2 Beta (if you closed it)
2. Under ‘Web Platform’, choose ‘Web Server’.  Select the following items to install
   • Static Content
   • URL Rewrite
   • CGI
   
3. Under ‘Web Platform’, Choose ‘Frameworks and Runtimes’.  Select the following item to install
   • PHP 5.2.9-2
   
4. Click ‘Install’
5. Click ‘I Accept’ if you accept the license terms and conditions
6. That is it!  PHP is installed and FastCGI is configured for you.

Test a PHP Sample Application

I have a very simple PHP application that you can use to test your install (as well as the rewrites later).  You can download it here.  If you have your own application feel free to use it.  Here are the steps I used to setup my test environment on my Windows Server 2008 VHD:

1. Create a directory called Demos
2. Download the sample application from the link above
3. Copied the TestPHP directory under my new demos directory.  (if you cannot seem to copy in your virtual hard disk, make sure you may need to install the virtual pc additions)
4. Register the virtual directory in IIS
   • Open IIS
   • Right-Click on your web and choose Add Virtual Directory
     
   • Set the Alias to ‘TestPHP’ and the Path to C:\Demos\TestPHP
     
   • Open a browser and navigate to: http://localhost/TestPHP/catalog.php.  You should see something like this:
     

To prove to yourself that php is actually running and configured, navigate to http://localhost/TestPHP/contactus.php.  Take a look at the code and you will see the line of code that adds the header ‘Contact Us’:

<?php echo "Contact Us" ?>

You can also navigate to http://localhost/TestPHP/index.php.  It will echo the results of phpinfo().

Add some UrlRewrite Rules

Remember that we have already installed the UrlRewrite 1.1 Module with the Web Platform Installer.  Let’s use this module so we can create some friendly URLs for our PHP Application.  We do this by adding rewrite rules.  I’m going to show you a feature that is new to version 1.1 called Rewrite Maps.  It acts just like it sounds.  It allows you to define simple rewrite maps (your basic from –> to mapping).  I would guess that this will be used pretty commonly when creating search-engine-friendly URLs.  Let’s take a look.

1. Open up IIS and click on your default web site.  Then double-click on Url Rewrite
   
2. Now we want to create our map.  Click on the ‘View Rewrite Maps…’ link on the right side.
   
3. Click ‘Add Rewrite Map…’
   
4. Click ‘Add Mapping Entry…’
   
5. Remembering that Virtual Directory name was ‘TestPHP’ and our catalog page was called ‘catalog.php’.  The URL to our page is: http://localhost/TestPHP/catalog.php.  We also had a page called ‘contactus.php’ (Url http://localhost/TestPHP/contactus.php). These are pretty ugly Urls. The extension ‘php’ means nothing to the general public.  Perhaps we want the Urls to look more like http://localhost/catalog and http://localhost/contact.  Let’s add the following 2 rules:
   
   
6. Now we need to add the rewrite rule that uses the map.  Click ‘Add Rules…’
   
7. Choose ‘Rule with rewrite map’
   
8. Leave the rule action set to ‘Rewrite’.  Under the ‘Choose the rewrite map’ section, choose the map you created earlier.  Mine was named ‘PHPTestMap’.  Click ‘OK’
   

Test It

Now we can type in our friendly URI into the address bar of our browser.  Nice.

Conclusion

As you can see, the Web Platform Installer makes configuring PHP to run on IIS a simple task.  You can also see the power of the IIS pipeline.  There are a wide array of modules like the UrlRewrite module that you can take advantage of.

Best of MIX Phoenix – Tim Heuer and Dan Wahlin speaking

I am psyched to announce that Tim Heuer (Community Program Manager for Silverlight) and Dan Wahlin (MVP, Consultant and Author) will be joining me to present at the “Best of MIX” MSDN Unleashed event in Phoenix on May 18th.  Details for the event are below.  Please make sure you register for the event.

What’s New in Silverlight 3?

Are you interested in building business-focused Rich Internet Applications (RIAs)?  Would you like to take advantage of 3D in the browser, but assume it is too hard?  Have you wanted to take a Silverlight application offline?  Then this session is for you.  We will explore and illustrate the new features of Silverlight 3, including the following:

· Support for perspective 3D

· Offline Support

· .NET RIA Services which simplifies the traditional n-tier application pattern by bringing together the ASP.NET and Silverlight platforms

Building Web Applications with Windows Azure

This session will begin with a brief overview of Azure and discuss some of the announcements made at MIX.  We will then illustrate through demo how to build a Windows Azure application from the ground up.  We will illustrate how to consume Azure Table Storage, how to host services, web pages and Silverlight components, as well as how to deploy your solution to the cloud.

MVC 1.0 vs ASP.Net Webforms

Have you heard about the new ASP.NET MVC  framework from Microsoft and wondered what it was all about? Are you curious whether this replaces ASP.Net WebForms?  Well in this session you will learn how to use the model-view-controller (MVC) pattern to take advantage of your favorite .NET Framework language for writing business logic in a way that is de-coupled from the views of the data.  In addition, we will talk about the pros and cons of both MVC and Web Forms, how to determine the best choice for a specific project, various techniques and patterns used to build MVC applications vs. Web Forms applications, and the implications for using each approach.

Hope to see you there!

Azure Application Part 3: Expose (REST) Web Service And Consume in Silverlight

This is part 3 in this series where I am building an Azure shopping cart application from the ground up.  In this post, I will create a RESTful service using WCF and host it in Windows Azure.  This service will source it’s data from Azure Table Storage.  I will then illustrate how to consume this service from a Silverlight component hosted in Windows Azure.  Giddyup.

(In part 2 I illustrated how to set up and access Azure Table Storage in both the development environment, as well as in the cloud.  I created a Wine table, added a few entities and retrieved them both locally and from the cloud.  I did all this taking advantage of the ADO.NET Data Services .NET Client Library and the StorageClient sample application.)

Watch the Screencast

deCast - Building an Azure App Part III: Hosting Web Services and Silverlight

Building Our RESTful Service

By now, you have more than likely heard of REST and have at least an ancillary understanding of it.  I further hope you have had the chance to develop RESTful services, taking advantage of our webHttpBinding in WCF.  If not, I invite you to look at my 10 part series on REST in WCF.  In that series, I provide an overview of REST and illustrate how to implement RESTful services using WCF 3.5.  The goal of this post is not to do a deep dive on REST, rather, to illustrate that you can host these WCF RESTful services in Windows Azure (as well as consume them from components hosted in and out of Windows Azure).  That being said, if you are not familiar, I will provide a 50,000 foot description of what REST is.  (please forgive me, but I am copying this description almost verbatim from an earlier post of mine)

REST Overview

REST is an architectural style that embraces the standards of the web such as HTTP and URI.  Because it is an “architectural style” there are endless debates as to what is RESTful and just what REST means.  I only intend to provide a general overview of REST here, as addressing that debate is beyond the scope of this post.  However, if you are interested in an in-depth understanding of REST, please read/view my 10+ part series of posts and screencasts on the subject.

In general, exposing services using a RESTful architectural style simply means embracing and adhering to the standards of the web.  What the heck does that mean?  Here are some examples:

• Treat everything as a resource and use URIs to uniquely identify resources.  My customers may be represented as http://www.robbagby.com/customers, whereas a single customer named fred may be represented as http://www.robbagby.com/customers/fred.  Finally my customers that have not paid may be represented as http://www.robbagby.com/deadbeatcustomers.
• Use the appropriate HTTP Verbs (GET, PUT, POST, DELETE) for the appropriate action.  Issue an HTTP GET to http://www.robbagby.com/customers/fred fetch a representation of fred, whereas issue an HTTP DELETE to the same URI to perform a delete action.
• Where appropriate, use standard representation formats (ATOM, XHTML, Microformats, etc.) to represent resources. 
• Use HTTP Headers appropriately
  • Use HTTP Status Codes to alert the caller as to the result of the call.
  • The Accept HTTP Header can be used to alert the server to the representation format you would prefer.
  • Use the Authorization header for authorization credentials.

The above list is certainly not an exhaustive list, but should give you a general idea of what REST is (with regards to services).

Why Build a RESTful Service

For the purposes of this post, we are going to create a simple GET service that simply exposes the Wines that we are storing in Azure Table Storage.  Why are we going to do that?  Azure Table Storage data is already exposed RESTfully, isn’t it?  Well there are a few reasons.  They are as follows:

• Perhaps we want to expose our wines without requiring authentication.
• Perhaps we want to expose our wines in a different representation format than ATOM (such as JSON or POX or whatever we feel like)
• Perhaps we want to massage the data prior to exposing it.
• Perhaps this data was not sourced in Azure Table Storage.  Perhaps this data was stored in SDS.
• We want to consume this data from Silverlight.  Silverlight precluded you from adding an Authentication header when making a request.  Therefore, as of now, you cannot directly access Azure Table Storage via Silverlight.
• This is a sample, so I want to keep this part simple.  I do not want to overcomplicate the sample with a bunch of data manipulation.

Implement Our RESTful Service

There are many ways to skin a cat (I just learned last night that this saying has nothing to do with felines, rather Catfish – go figure).  What I mean is that there are multiple ways to create a REST service with WCF.  There are 2 out-of-the-box templates and a bunch more in the WCF REST Starter Kit on CodePlex.  I am going to use the AJAX template (and de-AJAXify it) because it take a few steps and renders very clean code.  For production applications, I would strongly urge you to take a look at the WCF REST Starter Kit.  Enough babbling, here are the steps to create the service:

1. Right-Click on the AzureStore_WebRole project > Add > New Item
2. Choose the ‘AJAX-enabled WCF Service template and Name it: WineService.svc
   
3. The template did a few things for us:
   • It added references for us, including System.ServiceModel
   • It added a System.ServiceModel element in the web.config (if there wasn’t on, which in our example there wasn’t).  Under this node, it added the appropriate WCF Configurations, including an endpoint with our RESTful binding webHttpBinding and a pointer to an enableWebScript endpoint behavior (the AJAXiness of this template).
   • It added an svc file.  This file acts as the endpoint when hosting in IIS or WAS.  The file has a ServiceHost directive, pointing to the type that contains the service code, among other things as we’ll see in a minute
     
   • It added a class file that contains the implementation.  The ServiceHost above points both to the physical location of this class (CodeBehind), as well as the type (Service).  This class is where we are going to do our work.
   
4. Open the web.config and delete the System.ServiceModel section of the configuration (from <System.ServiceModel>… to </System.ServiceModel>).  This template used a configuration approach.  We are going to go with a configurationless model.  We do this by declaring a Factory in the ServiceHost directive in the svc file.
5. Open up the svc file (right-click on the svc file > View Markup).
6. Add Factory=”System.ServiceModel.Activation.WebServiceHostFactory” to the ServiceHost directive.  This is the configurationless model.  This factory will dynamically set up an instance of the WebServiceHost in response to requests.  It will set up a default endpoint, if appropriate, with the binding set to webHttpBinding, our REST-Friendly binding.
   
7. So, now we are all set up from a configuration(less) poing of view.  Now we just need to write the service for the code. 
   • Open WineService.svc.cs
   • Replace the code with the following:
     
8. That’s it.  We are ready to test.
9. Run your project (F5)  (remember that we are still pointing at Azure Table Storage in the cloud.  You might want to change your configuration settings back to point at local developer storage
10. Change the URI in Internet Explorer to the following:  http://127.0.0.1:81/WineService.svc/wines  Here is what you should see:
    
11. Cool, our service is working.  We now need to change the ResponseFormat back to Json.  Change the ResponseFormat to WebMessageFormat.Xml in WineService.svc.cs.
    

     

Create Our Silverlight Component

We are going to build a Silverlight component that will consume the RESTful service we just created. In this post, we will start building out the catalog component.  If you remember back to the first screencast, this is the portion of the application where the wines were exposed and you were able to page through it.  I will implement the paging in a future post.  What we are going to do here is to:

• Create a ListBox in Xaml
• Wire up an event handler for the loaded event
• Call our RESTful service
• Deserialize the response to a collection
• Bind our ListBox to the collection
• Pretty Up the Xaml

Well, now that we know what we are going to do, let’s get to doing it:

1. Add a Silverlight Application Project to the Solution:  Right-Click the Solution > Add > New Project > Silverlight > Silverlight Application
   
   
2. Leave the defaults on the Add Silverlight Application.  These choices will add this project to the Silverlight Applications for our web role, will create 2 test pages that by default contain a control from our project and setup debugging.
   
3. Add a ListBox directly under the grid. 
   • Give it an x:Name of WineListBox.
   • Set the DisplayMemberPath to ShortWineName.  I realize this is soooooo WinForms.  We will pretty this up in just a bit. 
     
4. Wire up a Loaded Event Handler to fetch the Wines
   • Open Page.xaml.cs
   • Wire up the event handler in the constructor
      
   • Add a private property that returns the root Uri to the web.  We will use this to calculate the Uri to our RESTful service
     
   • Code up the event handler for the loaded event.  Here we want to call our RESTful service
     
     • Start by using the helper method we created earlier to calc the Uri to our RESTful service
     • Create an instance of the WebClient class.  This is the simplest HTTP networking class to use in Silverlight.
     • We are going to call the OpenReadAsync method to issue an HTTP GET to our RESTful service.  The call is asynchronous (as are all networking calls in Silverlight), so we must first wire up an event hander to handle the response.
   • Add references to System.ServiceModel.Web and System.Runtime.Serialization.  We need these to use the DataContractJsonSerializer to deserialize the response.
     
   • OK, so now we are ready to write the callback method for our HTTP GET to our RESTful service.  This is where it may seem a bit tricky.  Remember that our service returns a List<Wine>.  The challenge we will have is that our Silverlight control has no concept of what a ‘Wine’ is.  That class exists on the server, and the control is on the client.  So what we need to do is to create a Wine class on the client that we can use to deserialize our response.
     
   • Write the event handler for OpenReadCompleted.  We will be passed the response as a Stream in the EventArgs.  We will use the DataContractJsonSerializer to deserialize the response.  Once deserialized, we can simply set the ItemsSource of the ListBox.
     
5. Test It
   
6. Pretty it up.  We got it working, but it isn’t very nice looking.
   • Open App.xaml
   • Add the Layout Styles and the ListBox Styles
     
     
   • Open Page.xaml
   • Delete the Height and Width attributes from the UserControl node
   • Update the layout of the control.  Replace the Xaml with the following:
     
   • Add a DataTemplate to the ListBox
     
   • Copy the Images Directory from the Web into the Silverlight Project
7. Test It
   

Well, now we’re getting somewhere!  It’s starting to look pretty good.  In the next post, I will implement paging, so don’t simply fetch all of the wines, rather we fetch a few at a time.  In future posts, I will illustrate how to use SOAP services instead of REST, implement the cart, security, and much, much more.  Until then…

MSDN Events Presents: The Best Of MIX

We have finalized the content and most of the dates for “The Best of MIX” events.  We will be bringing 3 great sessions to you, including “What’s New in Silverlight 3?”, “Building Web Applications with Windows Azure” and “MVC 1.0 vs ASP.Net Webforms”.  We have been working hard to bring you a fresh view of these topics, so please be sure to register, as these events tend to fill up fast.  You will find registration links, as well as a summary of the topics below.  I hope to see you there.

Registration Links

• Albuquerque, NM - May 4, 1:00 P.M. - 5:00 P.M.
• Salt Lake City, UT - May 6, 8:00 A.M. - 12:00 noon or May 6, 1:00 p.M. - 5:00 P.M.
• Colorado Springs, CO - May 28, 1:00 P.M. - 5:00 P.M.
• Denver, CO - May 26, 1:00 P.M. - 5:00 P.M. or May 27, 8:00 A.M. - 12:00 noon
• Ft. Collins, CO - (date and registration tba)
• Phoenix, AZ - May 18, 2009 1:00 P.M. - 5:00 P.M.

Summary

What’s New in Silverlight 3?

Are you interested in building business-focused Rich Internet Applications (RIAs)?  Would you like to take advantage of 3D in the browser, but assume it is too hard?  Have you wanted to take a Silverlight application offline?  Then this session is for you.  We will explore and illustrate the new features of Silverlight 3, including the following:

· Support for perspective 3D

· Offline Support

· .NET RIA Services which simplifies the traditional n-tier application pattern by bringing together the ASP.NET and Silverlight platforms

Building Web Applications with Windows Azure

This session will begin with a brief overview of Azure and discuss some of the announcements made at MIX.  We will then illustrate through demo how to build a Windows Azure application from the ground up.  We will illustrate how to consume Azure Table Storage, how to host services, web pages and Silverlight components, as well as how to deploy your solution to the cloud.

MVC 1.0 vs ASP.Net Webforms

Have you heard about the new ASP.NET MVC  framework from Microsoft and wondered what it was all about? Are you curious whether this replaces ASP.Net WebForms?  Well in this session you will learn how to use the model-view-controller (MVC) pattern to take advantage of your favorite .NET Framework language for writing business logic in a way that is de-coupled from the views of the data.  In addition, we will talk about the pros and cons of both MVC and Web Forms, how to determine the best choice for a specific project, various techniques and patterns used to build MVC applications vs. Web Forms applications, and the implications for using each approach.

Azure Application Part 2: Access Azure Table Storage

This is part 2 in this series where I am building an Azure shopping cart application from the ground up.  In this post, I will create a simplified ASP.NET version of the wine catalog.  We will create a table in developer storage (the local version of Azure Storage) to store our wines and write 2 web pages: 1 to view all wines and another to add a wine.  We will then access the same table in the cloud in Azure Table Storage.

(In part 1 I prepared my environment by setting up my development environment, creating a Windows Azure Account and creating a Hosted Service account.  I then created a Web Cloud Service project in Visual Studio and wrote a very simple “Hello, World” example.  I ran this sample locally and debugged it.  I then deployed it to the cloud.)  

Watch The Screencast

deCast - Building an Azure App Part II: Azure Table Storage

Add The 2 ASP.NET Web Pages

Let’s get started by adding the 2 ASP.NET web pages we are going to be working with in this post.  We want a page to view all wines (we will work with paging in a subsequent post) and a page to add a wine.  I don’t plan on illustrating editing a wine, but if I receive any feedback – hint, hint – I can change my plans.

1. Right-Click on the AzureStore_WebRole project > Add > New Item
2. Choose Web > Web Form > Name: ViewWines.aspx
   
3. Add a GridView (WineGridView) and a Button (AddWineButton)
   
4. Follow the same process as above to create a web form named AddWine.aspx
5. Add the following controls using whatever layout you wish (I know – tables are so 2002.  BTW, do you know when it is actually good practice to use tables?  When you want a table)
   
6. Download the images folder that contains the wine images from here
7. Add the Images folder (and it’s contents) to the  AzureStore_WebRole project

We’ll get back to these pages after we have our table set up…

A Brief Overview of Azure Tables

Azure Storage Tables are table-like structured storage.  I say table-like because they do not conform to the rows / columns structure we are used to for tables.  Azure Tables store Entities which are analogous to a row.  Entities are comprised of name-value pairs called Properties.  It is important to understand that Azure Tables do not enforce schemas.  Therefore, a table can store entities with wholly different structures.  However, the developer can choose to enforce schemas via code.

The Storage Account acts as the parent namespace for Table Storage, therefore you will not have any naming collisions with others that have similarly named tables.  Here is the best visual I could come up with to illustrate the structure:

You may have noticed that, unlike some other cloud storage systems, the properties are typed.  Here is a list of supported types:

• Binary
• Bool
• DateTime
• Double
• GUID
• Int
• Long
• String

There are 3 properties that every entity must have!  They are:

• PartitionKey (string) – Tables are partitioned.  The goal of Table Storage is to support massive scalability and availability.   We therefore load balance across storage nodes.  The partition key is used to tell the infrastructure that entities with the same partition key need to be stored together.  The partition key forms half of the entities primary key.
• RowKey (string) – The RowKey is other half of the dual key.
• Timestamp (DateTime) – This property is used to store the last modified date and is used for things like optimistic concurrency.

Setting Up For Azure Tables

In a previous post, I discussed ad nauseam the REST API for Azure Table Storage, the role of ADO.NET Data Services, as well as the purpose of the StorageClient application so I am not going to go into much detail here.  To summarize that post bullet style in less than 500 words:

• ADO.NET Data Services is a framework that allows one to easily expose and consume data services. 
• The framework includes a server library that exposes data securely as RESTful services, as well as client libraries to enable consuming these services easily.  One such library is the .NET Client Library.
• The ADO.NET Data Services team implemented a REST API that is compliant with the ADO.NET Services API, with some minor differences (for a listing of those differences, see this documentation). 
• One of the notable differences is the Shared Key (Lite) Authentication extension.  This is how requests to Azure Table Storage are authenticated. 
• The Windows Azure SDK shipped with a StorageClient sample application that extends the .NET Client Library, adding functionality such as signing the requests.

We are going to take advantage of the StorageClient sample application, using it as our API.  The nice thing about StorageClient and the .NET Client Library is that they completely abstract away the complexity of making these RESTful calls.  They hide the HTTP calls, the serialization and deserialization, as well as the message signing.  We just work with objects.  Let’s get started coding by creating the object that will represent our entity.

Create The Object That Represents Our Entity

We need to start by creating a class that represents our entity.  When fetching an entity from Table Storage, it will be deserialized into this type.  We will also use this entity for actions.  Let’s get started.

1. Add a reference to System.Data.Services.Client
2. Set a reference to the StorageClient library.  You can either add the sample project to the solution and add a project reference or you can add a reference to the compiled dll.  I am going to add the StorageClient project to the solution and add a project reference. 
3. Add a new class named Wine.cs to the AzureStore_WebRole project
4. Add 5 properties to the class. 
   • string ShortWineName (can be auto-implemented)
   • string WineLabelUri (can be auto-implemented)
   • string Vintage(can be auto-implemented)
   • double BottlePrice (can be auto-implemented)
   • int WineID (do not make it auto-implemented)
   
   

    

5. Implement class TableStorageEntity from StorageClient. 
   • You will have to import the Microsoft.Samples.ServiceHosting.StorageClient namespace
   • Remember that every entity in Table Storage requires 3 properties: PartitionKey, RowKey and TimeStamp.  The TableStorageEntity base class has these properties.
   • Every entity in ADO.NET DataServices needs to have a unique key.  ADO.NET DataServices uses a DataServiceKeyAttribute to annotate what the unique key is.  As pointed out earlier, the PartitionKey and the RowKey form a dual key.
   
   
   
6. Add a default constructor (this will be called upon deserialization), as well as a convenience constructor.  In the overloaded constructor we can call the base class constructor, passing the PartitionKey and the RowKey.  The base constructor simply sets those properties.  In this example I am not partitioning wines, so I set the PartitionKey to be the same for all wines.  I may address partitioning in a later post.  
   
7. If the convenience constructor is called, our entity is set up correctly and can be added to Table Storage.  If the default constructor is called, you will note that the PartitionKey is set, but the RowKey is not.  EVERY entity in TableStorage requires a PartitionKey, RowKey and TimeStamp.  The infrastructure handles the TimeStamp, so we only need to set the other properties.  It should now be clear why I didn’t use an auto-implemented property for WineID.  We need to set the RowKey in the setter.
   
8. That is it for the Wine Class.  Here is the complete code:
   

Create Our DataServiceContext Class

In a previous post detailing the REST API for Azure Table Storage I discussed the role of the DataServiceContext, as well as what the StorageClient’s TableStorageDataServiceContext class brought to the table.  To summarize, the DataServiceContext (part of the ADO.NET Data Services .NET Client Library) maintains state between interactions in order to support features such as identity resolution and optimistic concurrency.  The TableStorageDataServiceContext subclasses the DataServiceContext, adding functionality such as digitally signing the requests for authentication purposes.  Here we will create our TableStorageDataServiceContext:

1. Add a class named CohoContext to the AzureStore_WebRole project
2. Implement TableStorageDataServiceContext.  You will need to import the Microsoft.Samples.ServiceHosting.StorageClient namespace.
3. We now need to add a DataServiceQuery, exposing Wines, to the class.  Quoting Mike Flasko and Elisa Flasko from Expose And Consume Data in A Web Services World, “The DataServiceQuery object represents a specific query against the store defined using the URI syntax”.
   
4. That’s it for the DataServiceContext Class

Add Configuration Settings

We need to store the Table Storage configuration settings (our AccountName, our SharedKey used to sign the requests and the TableStorageEndpoint which is the URI to our TableStorage.  Remember that we may have multiple instances of our roles, so we store the configuration settings in the cloud service project.  Specifically, we add the configuration definitions in a csdef file, with the actual values in a cscfg.  Let’s add our settings.

1. Open the ServiceDefinition.csdef file from the AzureStore cloud service project.
2. Add a ConfigurationSettings node just below the end InputEndpoints.
3. Add 3 Settings: AccountName, AccountSharedKey and TableStorageEndpoint
   
4. Open the ServiceConfiguration.cscfg file from the AzureStore cloud service project.
5. Add the Settings with the development store values.  The development store values are the same for all machines.  Here is the full key: Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
   
6. We are done for now.  We will update these settings later when we create our Table Storage project in the cloud.  For now, we will work with the local development environment.

Create The Tables In The Development Store

The TableStorage class from the StorageClient sample has a static method named CreateTablesFromModel.  You pass it your context and your account information for authentication and it will infer a list of tables from every type in the context class that is derived from DataServiceQuery.  It will create those tables if they do not exist.  However, this does not work for development storage.  Not to worry, out friend Visual Studio knows how to do the same thing for us. 

If you didn’t know, the developer storage actually uses Sql Server to store the data locally.  Visual Studio can infer the list of tables, as well and will create the local tables.  Let’s do it:

1. Save and build your project
2. Right-Click on the cloud service project (AzureStore) and choose ‘Create Test Storage Tables’
   
3. Wait for the confirmation
4. (Optional) Open Sql Server Management Studio and look at the new database (AzureStorage) and table (Wine)
   

That is it.  We are ready to write some code, accessing the data.  Let’s get to it.

Build A Class To Encapsulate The Data Calls

1. Add a class named CohoDB to the AzureStore_WebRole project
2. Add GetWines, AddWine and InitializeTables static methods to the class.  We will call InitializeTables when working with the cloud storage.
   

   

Update Our Web Pages

Now it is time to consume our calls.  Let’s start with ViewWines.aspx.

1. Update the Page_Load with the following Code
   
2. (Optional) Format the GridView.  You can watch the screencast to see how I formatted the grid.

Now let’s update AddWine.aspx

1. Wire up an event handler for the SaveButton Click event
2. Implement the event handler.  Create the wine, call our AddWine method and redirect to the ViewWines.aspx page.
   

Test It

1. Set ViewWines as your start page and run the application (F5)
2. No wines exist so the grid will be empty
3. Click the AddWines button, add a wine and click Save
4. Repeat a few times

Here is what you should see (if you formatted the grid like me):

I fully realize that this is still somewhat ugly.  We will fix that in subsequent posts where we convert this to a Silverlight application.  The goal of this post was to introduce how to access table storage and make use of it.  The only thing we have left to do is to update the application to actually use the cloud and not the developer storage. 

Consume Table Storage In The Cloud

This is easier than you might think.  If you created a WIndows Azure Account, received your invitation token and redeemed it, all you need to do is to create a Storage Account.

1. Open the Azure Services Developer Portal
2. Click on Add Project
3. Click on Storage Account
   
4. Add a label, description and a name for your account.  This name must be globally unique.  Here is what you will see after you have created the project
   
5. Open the ServiceConfiguration.cscfg file from the AzureStore cloud service project.
6. Update the AccountName setting to the account name you created in step 4
7. Update the AccountSharedKey to the Primary Access Key you are given for your account
8. Update the TableStorageEndpoint to “http://table.core.windows.net/”.  DO NOT INCLUDE THE ACCOUNT NAME IN THIS SETTING.  In my case, I might be tempted to set the TableStorageEndpoint setting to “http://bagby.table.core.windows.net”, but THAT WOULD BE WRONG and I will be punished for it.

Once I have made those changes, I can test it again – Sort of.  We have to do one small thing.  Our Wine table was not created in the cloud. I need to make a call to TableStorage.CreateTablesFromModel in my code.  It is good practice to treat this method call similarly to how you treat a CREATE DATABASE call in traditional applications.  Many examples you will see will look like what you see below with the call in a Get or some other action.

While this works, it is inefficient.  I will keep it for this example, as I <insert some semi-valid excuse to hide the fact that I am lazy and this is the end of a long post>. 

Now we can access our data in the cloud.  After you have added a few wines like you did in the local storage demo, open up your favorite HTTP sniffer.  Mine is Fiddler.  Take a look at the traffic to prove to yourself that you are accessing the cloud.  Here is what it looks like for me:

In my next post, I will illustrate how you can expose your own custom services in Windows Azure.  Catch you soon…

Screencast Published - Building an Azure App Part I: Setup and Hello World

I have released the 1st screencast of a multi-part series where I will be building an Azure application from the ground up.  The application will be a shopping cart application with a Silverlight Front End.  The goal of this application is to illustrate various features of Windows Azure and in coming weeks, portions of .NET Services.  The first few posts will concentrate on Windows Azure, our Cloud Operating System.  I will illustrate things like the developer fabric, hosting various pieces of an application in the cloud (web pages, services, Silverlight components), as well as working with Azure Table Storage.  From there, we will keep going, adding and updating pieces of the application.
In this screencast (Part I), I will illustrate how to get your development environment, as well as a Windows Azure Hosted Services Project set up.  He will then build a simple "Hello, World" application, run and debug it locally and finally deploy it to the cloud. 
You can also read my Blog Post for great documentation on how to get your environment set up!

Azure Application Part 1: Setup and running “Hello World”

This is part 1 in this series where I am building an Azure shopping cart application from the ground up.  In this post, I will illustrate how to setup your development environment, setup your Azure Services Developer Portal, including the process of requesting a token.  I will then build out a simple hello world example, run it in the development fabric, debug it and finally publish it to the cloud.  If you are already familiar with these topics and are already set up, please feel free to go directly to part II (if it is published).

Watch the Screencast

deCast - Building an Azure App Part I: Setup and Hello World

Setting Up Your Environment

As I mentioned, the first few posts of this series deal strictly with Windows Azure offerings (we will be working with .NET Services and Sql Data Services in later posts).  This greatly simplifies setting up our development environment.  For this post, I will limit the setup information to what is necessary for Windows Azure.  As I delve into other areas, I will provide the necessary setup info.

Development Environment

A great thing about working with Windows Azure is that we have a simulated environment for you for development and testing.  We simulate both the Windows Azure Fabric, as well as Windows Azure Storage on you local machine so you are able to build and test applications taking advantages of these services without deploying to or accessing the cloud.  All you need to do is to install the following:

• The Windows Azure SDK
• Visual Studio Tools

You can go here to see details about pre-requisites for the SDK, but for your convenience, I have summarized below:

• Operating System
  • (for x86 version of SDK) - 32-bit editions of Windows Vista SP1 or Windows Server 2008.
  • (for x64 version of SDK) - 64-bit edition of Windows Vista® SP1 or Windows Server® 2008
• .NET Framework 3.5 sp1
• Sql Server
  • Express 2005
  • Express 2008
  • Local Instance of 2005, 2008 – See here for more details
• Internet Information Services (IIS) 7.0 must be enabled, with ASP.NET and Windows Communication Foundation (WCF) HTTP Activation - Click here for details how to configure

The prerequisites for the Visual Studio tools include everything above plus:

• Microsoft Visual Studio 2008 SP1 or Microsoft Visual Web Developer 2008 Express Edition with SP1
• Hotfix: Native Debugging Improvements
• Hotfix: Improve Visual Studio Stability
• Hotfix: Support for FastCGI on the Development Fabric

Set Up Your Windows Azure Account

With your development environment set up, you have everything you need to get started developing our Azure store sample application.  However, you might want to actually deploy this code to the cloud.  For that you are going to need an Azure account.  We are currently in CTP, so there is no charge for this account (that will chance when we go to release).  You do, however, need a token.

To Request A Token:

1. Navigate to www.microsoft.com/azure.  Click on Try It Now
   
2. Click on Try It Now to register with Connect and Request a Token
   
3. Log In with your Windows Live ID (you will need to create an account if you don’t already have one)
   
4. You will then have to complete the registration information (no screenshot required)
5. Click on the connection directory tab
   
6. Scroll until you see Azure Service Invitations
   
7. You are registered and should see a page like this:
   

To Setup Your Azure Services Developer Portal

1. Navigate to https://lx.azure.microsoft.com
2. Log In with your live id
3. Fill in your country and lanugage and press I Agree to create a new account
   
4. You will be re-directed to a confirmation page.  Press continue
   
5. You will be redirected to a page where you can redeem your invitation token.  This token is necessary to create a Hosted Services project, as well as a Storage project.  Don’t worry about closing the page or pressing cancel.  You will be re-directed here the next time you log in.  As I annotated below, you may have to wait a bit to receive your token (i.e. don’t proceed directly to Outlook and continually press refresh until you receive it).  We are in CTP and have a limited number of tokens to hand out at any given time.
   
6. Once you have your token entered appropriately, you will no longer see this page.  You will instead be re-directed to a page in the portal where you can create a project.  Here is what you would see if you chose ‘Cancel’ on the previous page or if you click the ‘New Project’ link under the ‘Summary Tab’.
   
7. Here is the view you would see if you had entered a valid token:
   
8. You are now ready to create your Hosted Services Project.  Click on ‘Hosted Services’ to add a new Hosted Services project.
9. On the next page, enter the following information:
   • Project Label – Enter a label for your Hosted Services project.  This label will be exposed on the Azure Services Developer Portal
   • Project Description – Enter a description of the project you will be hosting
   
   
10. On the next page, enter a service name – a unique service / domain name to create the unique DNS name.  You can check on the availability of service names.  After you have settled on a unique service name, press the ‘Create’ button.
    
11. Your project is now created and you are ready to deploy a solution.  We will get to that later.

* You can also take a look at the How Do I: Get Started Developing with Windows Azure? and the How Do I: Deploy a Windows Azure Application? screencast for walkthroughs on getting started with Windows Azure and deploying a Windows Azure Application.

Creating our Cloud Project in Visual Studio

Assuming that you set up your development environment as described above, you are ready to create your Cloud project.  In this part, we are going to create a “Hello World” web application, test it on the local development fabric and deploy it to the cloud.  In part II, we will access data from Azure Table Storage.  While you can also use Visual Web Developer Express, I am going to be using Visual Studio.  Let’s get started:

Create the Cloud Project

1. Choose File > New > Project from the Visual Studio Menu
2. Choose Cloud Service > Web Cloud Service
   
3. That’s it!

What was created?

It is kind of funny how I sometimes view project templates.  I almost assign some kind of magical value to them – like they just created life – when in reality, they are just templates.  They set up project files, add appropriate code files and set up config appropriately.  Perhaps I assign the magical value in the fact that it is so hard to create a good project template.  That should change with future versions of VS.  Anyhow, I digress.  The template created 2 projects.  The goals of these projects are as follows:

A Cloud Service Project

• Allows you to build and package your cloud application to run in the local development fabric
• Allows you to debug your cloud application in the local development fabric
• Allows you to build and package your cloud application to deploy to the cloud
• Stores configuration settings that apply to all instances of each role
• Allows you to configure the number of instances to be created for each role

A Web Role

A web role in this template is really just an ASP.NET application.  We have created additional web role projects, including a Cgi Web Role which allows you to host PHP and Ruby apps.  This template, however creates an ASP.NET application.

Add Some Code

1. Add a label to Default.aspx, giving it an ID and setting runat=”server”.
   
2. Add some code to Default.aspx.cs that executes on the server that sets the text of the label.  It doesn’t matter what you put here, we just want to illustrate that the server is doing some work and this is not simply a static page.
    

Run In The Development Fabric

Run It

Press F5 or the Start Debugging button to run the application in the development fabric.  Here is the result:

What Happened

The Visual Studio tool do some nice work for you.  Here is what happens.

• Visual studio created a Windows Azure Service Package.  This is the same package that is used to deploy to the web.  However, in that instance, the package is zipped and encrypted.  When running in the local development fabric, the extension of the package is csx and if you are running with debug symbols, you will find this in the debug directory. (See this post by Jim Nakashima for more information on how the service package is created)
  
• VS ensures that development storage is started
• VS ensures that the development fabric is started and deploys your package to the fabric (CSRun is the exe that does this)
• If you are running with debug symbols, Visual Studio will attach the debugger to a role running in the development fabric

(See this documentation for more information on the development fabric)

Debug It

Set a breakpoint on our code that sets the text of the label and start with debugging.  Here is what you see:

It is that easy to debug our applications.  Please note that it is not possible to attach a debugger to instances running in the cloud.  For those situations, you need to use logging appropriately.  We will cover that in future posts.

Deploy Our Application To The Cloud

* This section assumes that you have created a Windows Azure account, received your token and redeemed your invitation token as detailed above.  It also assumes that you have created a Hosted Services project.  I will use the token <accountName> to represent the label for the account.

Remember that when we publish to the cloud, we are packaging the application in the exact same way as when we are running it in the development fabric.  The only difference is that the file is zipped and encrypted.  Oh, and it has a different extension.

Here is the process to deploy to the cloud:

1. (optional) Set the application id in the project properties from your Hosted Service Application ID
   • Copy the application id from the Hosted Service Project to the clipboard
     
   • Right-Click on the cloud services project (AzureStore) > Properties > Portal
   • Paste the application id
     
2. Right-Click on the cloud services project (AzureStore) > Publish
   
3. A browser will be launched and it will automatically navigate you to the appropriate project if you completed step 1.  Otherwise, navigate to the Hosted Service project where you want to deploy.  An explorer window also opened to the location where the cspkg (encrypted, zipped project) and the cscfg files are.
4. Click on the Deploy button under Staging
   
5. Click on the Browse buttons and navigate to the publish directory under your project.  It is the directory the explorer opened to.
   
6. Click Deploy.  This process may take a few minutes.
7. Press Run.  This process may also take a few minutes.
8. When the WebRole reads ‘Running’, you are ready to test.
9. Click on the ‘Web Site Url’ link.
   
10. That is it, you are running in the cloud!  You are in staging, but feel free to swap it to production.
    

In my next post, I will set up Azure Table Storage.  I will create our Wine table for the catalog, write some code to add wines and fetch wines.  I will then write some simple aspx pages to consume that code.  Lastly, I will target the cloud instead of the local development environment.  Until then…

Building An Azure Application From The Ground Up

I have decided to start a multi-part blog/screencast series on developing an Azure application from the ground up.  There are 2 approaches one can take here: 1) Write the completed application first and then break it down into consumable pieces, with each piece becoming a blog post and/or screencast or 2) Write the application as you go along.  I am going to use a hybrid approach.  I have started an application, but will be adding and changing pieces as I move along.  Part of my reasoning is that, at the time of writing this post, not all of the Azure services are available, the most interesting of which is the new implementation of SDS (See Nigel Ellis’ MIX Session for more information).

Screencasts

• Part I: Setup and running "Hello World"
• Part 2: Working With Azure Table Storage
• (deep dive)  Understanding The Azure Table Storage API
• Part 3: Hosting Web Services and Silverlight

Blog Posts

• Part 1: Setup and running “Hello World”
• Part 2: Working With Azure Table Storage
• (deep dive)  Understanding The Azure Table Storage API
• Part 3: Hosting Web Services And Silverlight

The Sample Application

The sample application is relatively straight forward (at least to begin with).  It is re-using the same UI I used for a series I did on REST in WCF.  I will be building a shopping cart application.  The goal of this application is to illustrate various features of Windows Azure and in coming weeks, portions of .NET Services.  The first few posts will concentrate on Windows Azure, our Cloud Operating System.  I will illustrate things like the developer fabric, hosting various pieces of an application in the cloud (web pages, services, Silverlight components), as well as working with Azure Table Storage.  From there, we will keep going, adding and updating pieces of the application.

I look forward to your feedback, so please leave a comment!

Screencast Published - Understanding The Azure Table Storage API

Are you interested in Azure Table Storage?  Do you want to know about the REST API of Table Storage?  Do you want to know how we authorize calls to the service?  If so, I have released a new screencast breaking down the REST API of Azure Table Storage.  In this screencast, I illustrate consuming Azure Table Storage from a variety of means.  I show you the easy way, using the StorageClient sample application along with the ADO.NET Data Services Client Libraries, as well as making calls directly to the REST API using Fiddler as the client.

Take a look.  I really appreciate your feedback, so please leave me a comment!

Azure Table Storage, the REST and ADO.NET Data Services Story

Azure Table Storage is exposed via ADO.NET Data Services.  What the heck does that mean?  In this post, I will do my best to answer that question.  I will start with a brief overview of REST, the architectural style underlying ADO.NET Data Services.  As part of that topic, I will illustrate all we are doing when accessing Table Storage is issuing REST calls.  I will then discuss the role ADO.NET Data Services plays, as well as the role of the StorageClient sample application.

REST Overview

REST is an architectural style that embraces the standards of the web such as HTTP and URI.  Because it is an “architectural style” there are endless debates as to what is RESTful and just what REST means.  I only intend to provide a general overview of REST here, as addressing that debate is beyond the scope of this post.  However, if you are interested in an in-depth understanding of REST, please read/view my 10+ part series of posts and screencasts on the subject.

In general, exposing services using a RESTful architectural style simply means embracing and adhering to the standards of the web.  What the heck does that mean?  Here are some examples:

• Treat everything as a resource and use URIs to uniquely identify resources.  My customers may be represented as http://www.robbagby.com/customers, whereas a single customer named fred may be represented as http://www.robbagby.com/customers/fred.  Finally my customers that have not paid may be represented as http://www.robbagby.com/deadbeatcustomers.
• Use the appropriate HTTP Verbs (GET, PUT, POST, DELETE) for the appropriate action.  Issue an HTTP GET to http://www.robbagby.com/customers/fred fetch a representation of fred, whereas issue an HTTP DELETE to the same URI to perform a delete action.
• Where appropriate, use standard representation formats (ATOM, XHTML, Microformats, etc.) to represent resources. 
• Use HTTP Headers appropriately
  • Use HTTP Status Codes to alert the caller as to the result of the call.
  • The Accept HTTP Header can be used to alert the server to the representation format you would prefer.
  • Use the Authorization header for authorization credentials.

The above list is certainly not an exhaustive list, but should give you a general idea of what REST is.

Accessing Azure Table Storage via Fiddler

If Azure table is exposed via REST then we should be able to access it via Fiddler, right?  Well, we can.  The task is made a bit complex due to need for a valid authorization header.  When you create your Azure Storage project, a primary access key is created.  This is the key that you will use to sign your message.  This signed message gets passed in the authorization HTTP header.  The server will use this to authenticate your request.  If you have only used the StorageClient sample application as your API into Table Storage, then the authorization has been hidden (rightfully so) from you. 

In order to illustrate my point, I wrote a very simplistic application that will generate the URI to my table, an appropriate authorization header and the other required HTTP headers.  The following is a screenshot.

Here is how I did it: 

Some constants

I start by gathering the input.

Next, I calc some values:

• The URI
• Format the date according to RFC1123
• Create the string to sign
• Sign the string

Lastly, I list the HTTP headers, including the authorization containing the signed message.

That’s it.  We can use the output of our little sample application to access the data in my Wines table.  I will be using the Request Builder in Fiddler to issue my HTTP GET to the URI I calculated (http://bagby.table.core.windows.net/Wines), passing the HTTP headers I calculated, as well.  Here is a screenshot of the Request:

Here is a screenshot of (part of) the response:

As you can see, under the hood, all we are doing is making basic REST calls to Azure Table Storage.  While this knowledge may seem useless, I assure you that it is not.  I just got done writing a sample application illustrating how you can consume Azure Table Storage via a PHP application.  (That will be the subject of another blog post).  This knowledge was indeed helpful.  Well, now that we know what is going on at the lowest level, let’s explore the role ADO.NET Data Services plays.

ADO.NET Data Services

The goal of ADO.NET Data Services is to provide a framework to easily expose and consume data services.  The framework includes a server library that exposes data securely as RESTful services, as well as client libraries to enable consuming these services easily.  With regards to Azure Table Storage, the Azure team took care of implementing the server piece.  They chose to expose Azure Table Storage data with ADO.NET Data Services.  Armed with this knowledge, we can consume these services in a couple of ways: 1) consume them by hand or 2) take advantage of client libraries.

Consuming ADO.NET Data Services By Hand

Because ADO.NET Data Services is REST-based, any stack that is able to issue an HTTP request can consume these services.  In order to do so, you need to know the URI addressing scheme, which HTTP verbs to use and what the representation format of the response is.  Let’s examine each a bit further.

ADO.NET Data Services has a well documented URI addressing scheme.  All URIs are made up of three sections: service root, resource path, and query options.  The service root is simply the location of the root of the ADO.NET Data Service (ex www.robbagby.com/CustomerService.svc).   The resource path section is the part of the URI that identifies a resource.  Lastly, the query options section is where you can “represent directives that ADO.NET Data Services use to control the response to a request”.  The details of each of these are well documented here.  Someone calling a service by hand has all of the information they need to manually construct the URI.

The framework essentially uses HTTP as the API.  As such, the verbs like POST, GET, PUT, and DELETE are used for basic CRUD operations.  For instance, issuing an HTTP GET request to a URI will fetch that resource, whereas issuing a DELETE to the same URI will perform a delete action on that same resource.

ADO.NET Data Services support standard representation formats such as ATOM and JSON.  This makes it easier to work with the response.  These are well documented formats and many stacks have serializers that understand how to work with these formats.

To summarize, it is clearly possible to consume ADO.NET Data Services manually.  In fact, we illustrated that in the demo above.  The process begins with constructing the URI to the appropriate resource.  The next step is to issue the HTTP Request with the appropriate HTTP headers and HTTP method.  The final step is to handle the response by parsing it or taking advantage of a serializer (we skipped this step above).

Taking Advantage of Client Libraries

While it is possible to consume these services by hand, it is certainly not easy.  For that reason, ADO.NET Services provides client libraries to allow differing technologies such as .NET, Silverlight and AJAX clients to easily access these services.  These libraries abstract away the complexities of issuing HTTP Requests, as well as provides the ability to handle the response as objects.  Currently, there are libraries for .NET, AJAX, as well as Silverlight clients.

The following excerpt from Expose And Consume Data in A Web Services World by Mike Flasko and Elisa Flasko does a good job at providing a high level overview of the Silverlight and .NET client libraries for ADO.NET Data Services:

“The .NET Framework and Silverlight client libraries consist of two primary types, the DataServiceContext class and the DataServiceQuery class. DataServiceContext represents the runtime context for a given data service. Data services themselves are stateless; however, the context in which the developer interacts is not, and state on the client is maintained between interactions in order to support features such as identity resolution and optimistic concurrency. The DataServiceQuery object represents a specific query against the store defined using the URI syntax. To execute a query and obtain the results in the form of .NET objects, you simply enumerate over the query object. You can do so using the standard "foreach" construct in C# or "For Each" in Visual Basic®, for example.”

The following example illustrates the ease by which one can consume ADO.NET Data Services Data with the .NET Client library.  Please note that this example is consuming ADO.NET Data Services exposing an Entity Framework Entity Data Model not consuming Azure Table Storage Data – we’ll get into that later.

We started by creating an instance of the client library type DataServiceContext.  Our context happened to expose a DataServiceQuery named Wines.  We simply wrote a nice LINQ query, targeting that DataServiceQuery.  Under the hood, the LINQ query was evaluated into the appropriate URI.  The URI looks something like this:

http://localhost/AstoriaSample/Coho.svc/Wines()?$filter=WineType/WineTypeName eq 'Reds'&$expand=WineType

When we began to iterate over the results, an HTTP GET was issued to that URI.  The response was automatically deserialized into client-side Wine and WineType proxy classes for us.

So where did we get these client proxy classes (the DataServiceContext, Wine Class, etc.).   We got them by either calling DataServiceUtil directly or by right-clicking on our project and choosing “Add Service Reference”, passing the service root URI.  Either way, all of the proxy classes are generated automatically.  While, in many ways, these are really just implementation details that are (and should be) abstracted away from you, having a high-level understanding of what these are goes a long way in understanding the role of the StorageClient Azure Sample.

The StorageClient Sample Application

The Windows Azure SDK shipped with a sample called StorageClient.  At the time of writing this post, this sample is really the API you will typically use to consume Azure Table Storage if you are coding in .NET.  That probably seems confusing as I just got done explaining how we already have a great .NET client library for ADO.NET Data Services.  Don’t worry, the sample still uses those libraries.  However, the StorageClient adds some Azure-specific logic.  The most important of which is the logic to digitally sign the requests.

As you can see below, the StorageClient includes a TableStorageDataServiceContext that implements the .NET client library DataServiceContext.  This subclass wires up an event handler for the SendingRequest event.  In that handler resides the signing logic.  All of this is abstracted neatly away from the consumer.

Consuming Azure Table Storage via the StorageClient

Below is some code that is targeting Azure Table Storage via the StorageClient.  You will notice that the pattern is roughly the same as before.  The caller need not be aware of the complexity of the call or signing the message.  All they need to do is set up their configuration correctly (3 settings) and have at it.

There is certainly more to the StorageClient than I have shown, but I hope that this post has helped you understand a little how Azure Table Storage is exposed RESTfully, as well as the role of ADO.NET Data Services and the StorageClient sample application.

XamlFest in Salt Lake City on May 1

I am excited to let you know that we will be bringing XamlFest to Salt Lake City on May 1.  it was originally scheduled for mid-April, but was rescheduled due to conflicts.  If you are wondering what XamlFest is then here goes:

“Are you excited about the WPF but concerned about the learning curve?”

“Have you seen Silverlight but don’t know where to get started?”

“Or are you curious about how tools like Visual Studio and Expression Blend help designers and developers work together to deliver great user experiences?”

If so, join us at XamlFest!  XamlFest is an interactive event where you’ll learn about the platforms, tools, and processes used to deliver differentiated user experiences. It’s a chance for you to mingle with UX-minded Microsoft folks.  To register, please send an e-mail with the names and e-mail addresses of your attendees to xamlfest-slc@live.com.

Entity Framework Modeling: Select Stored Procedures

In my last post, I illustrated how to map action stored procedures (insert, update, delete) to entities.  In this post, I will illustrate how you can import select stored procedures and map the results to entities. 

Watch the Screencast

You can watch the screencast here.

Index of Related Entity Framework Blog Posts and Screencasts

Here is an index of other blog posts and screencasts I have done on this subject.

Setting up the scenario

Before I import the stored procedure, I want to simply illustrate some EF functionality that doesn’t take advantage of select stored procedures.  We’ll add that functionality in later.  We are going to create a relatively simple Entity Data Model from the data model below. 

Step 1: Add the Entity Data Model

Step 2: Generate the Model From The Database

Step 3: Choose the source tables

Step 4: Name the Entities appropriately

Set appropriate Entity and Entity Set names for each of the entities.  Simply single-click each entity and set the values in the properties pane as seen below (I single-clicked the person entity):

The names I set were (Entity Name, Entity Set Name):

• Person, People
• PersonCategory, PersonCategories
• StudentCourse, StudentCourses
• Course, Courses

Step 5: Write some code to query

By default, the EF does not load relationships.  There is no way for the framework to know which relationships to load unless you tell it.  You will notice that I used lazy loading to load the relationships.  Alternatively, I could have used Include statements to do eager fetching.  If you are not familiar with these 2 options, let me do a brief overview. 

Eager Loading

You can direct the framework to eagerly load relationships by using an include statement (seen below).  With an eager load, the framework will construct a join query and the relationship data will be fetched along with the original entity data.

Sql Profiler Trace Result

Lazy Loading

With lazy loading, an additional query is constructed and run for each call to load to fetch the relationship information.  In the code below, an additional query will be run for each Person p.  In certain instances, eager loading is the way to go, while in others, lazy loading is a better approach.

Sql Profiler Trace Results

One of the additional queries run for the relationship

Query Results

Keeping in mind that we chose to go with the lazy loading approach (it will become why clear later), below are the results from our code.  Notice that only the people of type Student or BusinessStudent had classes.  Also notice that there was 1 Student and 2 BusinessStudents.  This will be important in our demo.

We now have the baseline code written and we can move on to mapping a select stored procedure.

Map in the Select Stored Procedure

Step 1: Write the Stored Procedure

Step 2: Update our model – Add the stored procedure to the model

Step 3: Create a function Import

Step 4: Update our code to call our function

The only change I made was to call our function.  Here are the results:

Our spGetBusinessStudents stored procedure was called when we started to iterate over the results.  At this point, it should be clear why I used lazy loading in the example.  Because stored procedures are not composable, we need to lazily load the relationships. 

Conclusion

The Entity Framework provides us the capability to import stored procedures as functions.  We can then map the results of the function back to our entity types.  We then have the ability to traverse relationships from those entities, as long as we use lazy loading.  In my opinion, this is great support for select stored procedures.

Entity Framework Modeling: Action Stored Procedures

One of the biggest concerns I hear when discussing the Entity Framework is that of security.  People are initially impressed and excited about the ease of developing a conceptual layer.  Thanks to the magic of the Entity Framework and object services, you have an object layer that you can interact with that is mapped to your database.  The excitement, however, wears off when people figure out that the default behavior for the action queries (insert, update and delete), along with selects is to generate dynamic SQL.  In my humble opinion, this is a viable concern.  In this post, I will discuss the security concerns with this default behavior and illustrate how you can map stored procedures to the actions.

View the Screencast

You can watch the screencast here.

Index of Related Entity Framework Blog Posts and Screencasts

Here is an index of other blog posts and screencasts I have done on this subject.

The benefits of SPs over Dynamic SQL

You are, no doubt, aware of the security benefits of using stored procedures.  SPs are parameterized (unless you create dynamic SQL within the proc) and are therefore not susceptible to SQL Injection attacks.   Further, you can limit the damage a user account can do by just assigning them execute permissions on specific stored procedures.  You do not need to give them any permissions to the underlying tables.  So, how does this compare to dynamic SQL?

Again, most of you know that parameterized SQL statements are also not susceptible to SQL Injection attacks, so on this account they are equal (well stored procs force you to parameterize so maybe not absolutely equal).  The SQL generated by the EF are parameterized and are therefore safe in this regard.  I’ll illustrate that in the next section.

The big difference between the two approaches is assigning permissions.  For stored procedures, all you need to do is grant Execute permissions for the SP.  However, for SQL statements, you must grant permissions on the underlying table or tables (see below).  That can be quite scary.  Whereas a stored procedure can limit a users capabilities to only deleting specific records (perhaps only those associated with them), delete permissions on the underlying table give you no such control.  It should be crystal clear why the use of stored procedures for actionable queries are preferable.

vs.

Creating the Entity Data Model

I’m going to start with creating an Entity Data Model and pointing out the default behavior.  For the purposes of this post, I am going to use a very simple Entity Data Model.  I will have one entity: Person that is mapped to a Person table.  I am using this table, as it has only a few required fields and will be easy to demo with.

Step 1: Add the Entity Data Model

Step 2: Generate the Model From The Database

Step 3: Choose the source table

We only need the Person table here. 

Step 4: Name the Person entity appropriately

You should give the entities and entity set appropriate names.  I named the entity Person and changed the EntitySet name to People.  The easiest way to rename the entities and entity sets is to single-click on the entity in the designer and make the updates in the properties pane:

Examining the Default Behavior for Actions

I’m going to put together some code that, along with SQL Profiler, will illustrate the default behavior.  The following is the code in a console app that inserts a new Person, utilizing the entity we just built.

Code:

Profiler Result:

As you can see, the default behavior is for the framework to generate some SQL dynamically and execute it.  You can further see that the generated SQL is parameterized and you are safe from SQL Injection attacks.  However, the user under which this sql is executing must have insert permissions on the table.  For delete actions, the user must have delete permissions on the Person table, and so forth.

Mapping Stored Procedures To Your Entities

Well, now that we know about the benefits of stored procedures and we have seen the default behavior, let’s illustrate how to map some stored procedures to your entities.  Let’s get started:

Step 1: Write the Stored Procedures

Insert:

Update:

Delete:

Step 2: Import the procedures

In the model browser, right-click and choose to update the model from the database

Add the 3 procedures we just wrote:

Step 3: Map the entities to the procedures

Bring up the stored procedure mapping

Map the appropriate procedure to the appropriate function.  Seen below, I am mappting the spAddPerson procedure to the Insert Function.

Because the parameters for the stored procedure line up with the property names on the entity, the designer will map everything appropriately.  If there are naming differences, you simply need to update the map. 

You have to do one other thing before you are done.  In our data model, the Person table has an identity column: PersonID.  The identity is assigned by the database when a row in inserted.  That is why our stored procedure has the clause: SELECT SCOPE_IDENTITY() as Id.  We need to map this result column to the PersonID on our entity.  That way, when the entity is added to the database, the new PersonID is then reflected in the entity.

The insert in the hardest of the 3.  Simply map the spDelPerson to the Delete function and spUpdPerson to the Update function.  The properties are named appropriately, so they will line up.

That is it!

Running the Insert Again

I’m ran the exact same code as before.  Here is what Profiler showed now:

Conclusion

As you can see, it was quite simple to map the actions to stored procedures.  There are no changes required to the calling code.  You simply map the procs to the appropriate action in each entity.  This simple functionality should go a long way toward making you feel comfortable taking advantage of the Entity Framework.  In my next post, I will illustrate how you can map select stored procedures into the entity framework.

Entity Framework Modeling: Table Per Hierarchy Inheritance

In a previous post, I illustrated how you can implement table-per-type inheritance in your model.  You use table-per-type if your data model splits information for different logical things between tables that have 1:1 relationships.  Some data models store multiple logical things in one table and use a discriminator column to advertise what kind of thing it is (please excuse the use of the word ‘thing’ – all of the good words like entity and type have alternate meanings that could cause confusion).  With data models such as these, you can implement table-per-hierarchy inheritance.  With table-per-hierarchy, you can model the same type of inheritance between entities as in table-per-type.  The difference is that all of the entities are sourced from a single table, with the discriminator column being used as the differentiator.

Watch the screencast

You can watch the screencast here.

Examining the Data Model

As discussed earlier, this data model only has 1 table.  I have annotated the model to illustrate which columns are associated with each type of person (Student, Instructor, Admin and BusinessStudent).  I have further pointed out that PersonCategory is the discriminator column.  If this column contains a 1, it indicates that the person is a student, a 2 indicates an instructor, a 3 indicates an admin, while a 4 indicates that the person is a business student.

From this model, we want to create an entity hierarchy with a Person entity being the base.  We then want to create 3 entities (Student, Instructor and Admin) that inherit from Person.  We then want to create a BusinessStudent that inherits from Student.  The resulting hierarchy will be exactly like the hierarchy I created in this post.

Implementing Table Per Hierarchy

Step 1: Add the Entity Data Model

Step 2: Generate the Model From The Database

Step 3: Choose the source table

We only need the People table here.  It contains records for each of our entity types

Step 4: Name the Person entity appropriately

You should give the entities and entity set appropriate names.  I named the entity Person and changed the EntitySet name to People.  The easiest way to rename the entities and entity sets is to single-click on the entity in the designer and make the updates in the properties pane:

Step 5: Add the derived entities

We now need to add our derived entities.  We want to add 4 new entities in all: a Student, Instructor, Admin and BusinessStudent.  For the first 3, name them appropriately and set the Base type to Person.  For BusinessStudent, set the Base type to Student.

Your model should now look like this:

Step 6: Cut and paste the properties from the Person entity to the appropriate entities.

Simply single-click on the property in the Person entity and press ‘ctrl + x’.  Then single-click on the Scalar Properties section of the appropriate entity and press ‘ctrl + v’. The properties to cut and paste are as follows:

• HireDate –> Instructor
• EnrollmentDate –> Student
• AdminDate –> Admin
• Credits –> Student
• Degree –> Student
• BusinessCredits –> BusinessStudent
• Discipline –> BusinessStudent

Step 7: Delete the discriminator column property from Person

You need to delete the PersonCategory property that the designer created in the Person entity.  This column is used as the discriminator.  Simply single-click on the PersonCategory property in the Person entity and press the delete key.

The model should now look like this:

Step 8: Map the new derived entities to the Person table and set the discriminators

Now we need to set the discriminator by adding a condition:

Once you have mapped all 4 entities to the person table and have set a condition on all 5 entities (including the Person entity), you are done and ready to exploit this model.

Consuming the Model

Results:

Conclusion

As you can see, we have built a complete inheritance hierarchy that sources from a single table.  In fact, from an application standpoint, the hierarchy is exactly the same as the one we built in our table-per-type example.

Entity Framework Modeling: Entity Splitting Part II (adding inheritance)

In Entity Splitting Part I, I illustrated how you could map multiple tables to a single entity.  In the post previous to that, I illustrated how you could build a completely different conceptual layer for the same model by implementing table-per-type inheritance.  These are 2 completely different modeling scenarios.  Entity Splitting results in a much simpler model, while table-per-type results in a more flexible model where you are able to cast between types and take full advantage of all of the benefits of inheritance.  In this post, I want to illustrate that this is not necessarily an either-or decision.  You can mix and match if it meets the need of your application.

Revisiting The Data Model

As you can see from my annotations, our goal here is to create a “hybrid” model, implementing entity splitting along with table-per-type.  I will create a Student entity that is sourced from 2 tables: PersonTPT and StudentTPT.  I may choose to do this if there is no benefit to having a Person entity in my conceptual layer.  Perhaps I am building a student system and all I ever work with are students of varying types.  Now, there may be a need in my model to build out an inheritance hierarchy where the base type is Student.  We can use the Student entity we implemented using entity splitting in Part I.

Revisiting the results of Part I

In Part I, we added 2 tables, PersonTPT and StudentTPT, into our model and mapped both tables to a single Student entity.

Creating the BusinessStudent Entity and implementing inheritance

The steps below follow pretty closely the steps laid out in my table-per-type post.

Step 1: Add the BusinessStudentTPT table to the model

In the model browser, right-click and choose ‘Update Model from Database…’

Choose the BusinessStudentTPT table

It will look like this:

Step 2: Rename the entity

Step 3: Remove the default relationship

Step 4: Create the inheritance relationship

When you are done, the designer should look like this:

Step 5: Delete the derived-entities key properties

When we added the BusinessStudentTPT table, the designer looked at the table schema and added a property for each table column, including one for the PersonID column.  The PersonID is a key between the entities and will be inherited from the Student entity.  Therefore, we do not need this property set on each of the derived entities.  Simply single-click on PersonID on BusinessStudent and press delete.

Step 6: Map the PersonID column to the inherited PersonID property

In step5, we deleted the PersonID property on the BusinessStudent entity, because it is inheriting this property from the base.  Because we deleted this property, the PersonID column from the underlying BusinessStudentTPT table is no longer mapped.  We need to map it to the inherited PersonID property.  Simply choose the PersonID from the dropdown box.

We are done and can now test our model.

Consume the hybrid Model

There are a couple of ways to illustrate how to exploit our new model.  In the below code, you can see that we are able to iterate over our Student entities and access properties that are sourced from the 2 tables: PersonTPT and StudentTPT.  This is thanks to entity splitting.  You can also see that I am doing a type check and if the type is BusinessStudent, we will do some additional processing.  In this case, simply writing some BusinessStudent-centric information to the console.

Here is the output:

Another option would be to change our query to only return BusinessStudent types:

Conclusion

It should be clear from this post that you are able to take advantage of both entity splitting and table-per-type inheritance if the need suits you.