Weekly Update – New REST and ‘Oslo’ Screencasts

Weekly Update – New REST and ‘Oslo’ Screencasts

I had originally used the title ‘This week in downloads’…well, because there were downloads. 🙂 But this feels a bit like hollow advertising, and I may shop around for a new title (suggestions are always welcome), but I’ll go with the very bland ‘Weekly Update’ title for now.

New to the web this past week:

Otherwise, we are continuing to focus on building out materials that will be appearing in the month of September – new MSDN pages, new articles, and a couple virtual labs.

While I Was Sleeping: New SharePoint Tools by U2U

While I Was Sleeping: New SharePoint Tools by U2U

During my holidays my colleagues at U2U have released several pretty cool SharePoint tools/extensions. I’m just going to list them, if you want to learn more about them, check out Karine’s blog.




  • U2U List Properties Feature Package
    The U2U List Properties Package has been developed to ease the work of a SharePoint 2007 developer. It adds an hyperlink to the List Settings page displaying a page with detailed information about the list properties.


  • U2U Site Properties Feature Package
    The U2U Site Properties Package has been developed to ease the work of a SharePoint 2007 developer. It adds an hyperlink to the Site Settings page displaying a page with detailed information about the site properties.


  • U2U Job Definition Configurator Package
    This feature provides SharePoint administrators with a user interface to schedule and reschedule custom job definitions. 

On top of that Karine has updated her famous CAML Builder Feature with the following enhancements (more info and download):




  • Code snippet generation


  • DateTime enhancements


  • Query options for SPQuery


  • Enhancements for Calendar lists

A Case Against Code Reviews

A Case Against Code Reviews

I know, it sounds odd in the modern world where code reviews are almost like one of the Sacred Commandments, that is taken religiously and you could be burned at the stake for not respecting it. So, please, hold with me for a little heresy No, I don’t argue that code reviews are valuable. It’s just everything in this world has cons and pros, and I’d like to discuss one unusual “con” of code reviews that usually does not come to light.


Anyway, imagine a small team very busy doing the work, that is, new features for your product. I stress that: everybody is busy. No kidding, real busy. And, surprise!, just like every other product, yours has bugs. And bugs are to be fixed, right? Right.


Now, how you’d fix a bug? There are generally, two philosophies about fixing the bugs. Well, may be more, and of course, there is that stupid “just fix the bug”, which completely ignores metaphysical side of the things we are discussing right now, but let me ignore this one for a while. So, these two approaches are patching vs. refactoring.


Now, what would you think is the right way to fix bugs? Admittedly, there are cases when patching is acceptable Examples? Quick Fix Engineering patches. Products, which are really done, and the less you touch them the better. Fixing embedded code of a space station passing a Jupiter, where every byte of the fix increases the chance of the whole fix to be corrupted and disable a multi-million irreplaceable spacecraft.


However, in most cases and in what’s considered “good engineering”, I strongly believe that refactoring is far superior to patching. It does not mean that every small bug requires complete rewrite of the product, not at all. But it means that you have to consider a bigger frame and not be afraid to change quite a bit, if necessary.


I know, I know, it sounds theoretical and questionable, so let me give you an example. Considering short size of an article, I’ll have to give a very simplified example, but quite a valid one nevertheless. Suppose, you have a method called DownloadCompletedInstant(), which is a callback at the moment, when some download is completed. In fact, all it does is to allow you to start downloading the next file. You find a bug, when one of our colleagues added to it something really really stupid, because he was confused with “Download completed” part of the name. In fact, it would not be stupid, if it would be in DownloadCompleted() callback instead of DownloadCompletedInstant() one. So, now you have two options:


1. Just move your colleague’s code from DownloadCompletedInstant() to DownloadCompleted()


2. Same as (1) plus renaming DownloadCompletedInstant() into ScheduleNextDownload(), hence avoiding a chance of future confusion.


So, what would you do? (2), clearly, right? However, there is a little problem. The renamed call is used in ten other files. So, although the change is microscopic, it affects much more files than a simple patch.


Now, your team is doing code reviews, so what’s the higher chance of getting it fast – posting a change with just a few lines of changes in a single file, or a changes with several dozen lines changed in a dozen or so files? And don’t forget, you want it fast. In part, because you want to fix the bug and get to the next, in part, because you don’t want the fix sitting on our computer and not being checked in. But! Everybody else is busy too. Everybody else has their own bugs. So, naturally, you would rather get a change with minimum affected lines just to get your colleagues do code review faster.


The result? The product gets a patch, not refactoring, and in a couple of months somebody will again misuse DownloadCompletedInstant() for something else, as bad as this time or even worse.


So, does it look right? Is it just me or is there a real problem somewhere here?

BizTalk Message to System.String in BizTalk Server 2006

BizTalk Message to System.String in BizTalk Server 2006

I’ve needed to cast my BizTalk message as a System.String in a couple of occasions so I’m going to put it here to remember how to do it.
1. Create a Variable of type System.Xml.XmlDocument (I’m calling it xml_Temp here)
2. Create a Variable of Type string (I’m calling it str_MessageAsString here)
3. In the expression shape insert the following code:

//Instantiate your xml_Temp System.Xml.XmlDocument
xml_Temp = new System.Xml.XmlDocument();
//Assign the message you want as a string to your new xml_Temp System.Xml.XmlDocument
xml_Temp = msg_YourOriginalMessage;
//Assign the .OuterXml property of your xml_Temp to your str_MessageAsString System.String
str_MessageAsString = xml_Temp.OuterXml;

REST in WCF – Part IX – Controlling the URI

REST in WCF – Part IX – Controlling the URI

(click here for an index of the complete series, as well as supporting screencasts)

(click here for a screencast illustrating "Controlling the URI")

Resources in REST

Arguably, the most fundamental concept in REST is that of a resource.  It is best to think of it as a conceptual representation of an entity or entities.  Blah, blah, blah, conceptual, blah blah blah, representation, blah, blah, blah entity.  What does all of that mean anyway?  Think of it this way, if you can create a link to it, it is a resource.  Now what does conceptual representation mean?  Essentially, it means that the resource is an abstraction.  It is not the underlying entity itself, rather a mapping to that entity… and that mapping may change.  Whoa, the mapping may change?  How is that?  Consider the example that you wanted to expose the top 10 best selling books at your online store.  The resource would be those top 10 best selling books.  It is clear that those would change over time. 

The need for the abstraction should be clear.  In our previous example, we don’t really care what the back end was  that stored the top 10 best selling books.  It was, more than likely, a database system.  It could have been Microsoft Sql Server, or it could have been Oracle or Informix or something altogether different.  We don’t really care because we are not interested in the entity itself, rather the representation.  If we were to switch back ends out after a period of time, it would be meaningless to us.  The representation would be unaffected (although, as we argued earlier the representation might have changed).  Further, imagine the complexity of the system where we were not mapping to the concept, but to the actual underlying entities. 

URIs in REST

The way in which you identify a resource is through a URI.  Section 6.2.1 of Fielding’s dissertation points out that "The definition of resource in REST is based on a simple premise: identifiers should change as infrequently as possible."  He further states that "authors need an identifier that closely matches the semantics they intend by a hypermedia reference…"  This points out the importance of the structure of the URI.  Many folks try to create what I refer to as "Hackable" URIs.  These are URIs that are easily remembered and whose structure and semantics are clear enough to manipulate.  Take for instance the following URI: ‘http://www.someuri.com/Product/Flange’.  It is pretty clear the the structure is: the http scheme and the hostname (‘http://www.someuri.com’) followed by 2 segments: Product and ProductName.  A template for this might look like the following:  ‘http://www.someuri.com/Product/{ProductName}’ where {ProductName} represents a variable.

You might argue that this is bad design, in that if the name of the product changes, so must the URI and that clearly violates the premise that a resource is based on.  Another approach would be to use the ProductID as the final segment.  I’ll leave that up to you.  What I want to discuss in this post is what your options are for controlling the URI, assuming you have already designed how the URI should look.

The approach of this Post

If you have ever seen ‘What About Bob’ with Bill Murray, you will understand the following reference (if you haven’t, close your notebook, go to Blockbuster, rent ‘What About Bob’, come home, put it in the DVD player, open a beer – if that is your thang – and watch it).  We are going to take baby steps to controlling the URI.  I am going to start by outlining the default URI behavior when using the webHttpBinding along with the webHttp endpoint behavior.  I will then show you what your options were in manipulating the URI structure via the UriTemplate.  I’ll then move on to some additional functionality available in SP1.  Lastly, I’ll illustrate how you can take complete control over the structure of the URI using IIS7 and the Url Rewrite Module.

The Sample

Below you will see the service contract and operation contract of our sample service.  As you can see, the operation is named GetWine and takes in a string of wineID.  You will also note that I have decorated the operation contract with a WebGetAttribute, making this callable via an HTTP GET.  I have omitted the implementation, as well as the configuration, as they adds no value to this discussion.

[ServiceContract]
public interface IRESTWineService
{
    [OperationContract]
    [WebGet(ResponseFormat = WebMessageFormat.Xml)]
    WineData GetWine(string wineID);
}

One other point to make is that address to this web is http://localhost/RESTControllingUri.

The Default Behavior

It may not be clear, but this operation does have a unique URI associated with it.  The default URI scheme is the path to the *.svc file, followed by a segment with the operation name, followed by querystring parameters for each operation argument.  The following represents the default structure of the URI:

[protocol]://[hostname][:port][/path][/svc filename][?argument1=value1[&argument2=value2 …]]

In the case of our example, it looks like this:

image

The UriTemplate

When we released the webHttpBinding and the webHttp endpoint behavior in WCF 3.5, we provided the ability to define a UriTemplate.  Aptly named, the UriTemplate allows you to define a template for a set of URIs that follow a similar structure or pattern.  The UriTemplate has 2 parts: the path and the query.  The path is a series of segments.  The segments can contain literals, parameters or variables and wildcards.  Here are some examples:

  • literal:  /products
  • literal:  /products/sportinggoods
  • literal and variable:  /product/{productId}  (Where productId is a parameter that is mapped to an operation argument)
  • wildcard:  /products/*

The query contains name-value pairs that represent the querystring parameters collection.  Here are some examples: 

  • literal in query:  /products?type=json
  • variable in query:  /products?index={index}&pageSize={pageSize}

You can set a UriTemplate through code or you can pass it as a parameter to a WebGetAttribute or WebInvokeAttribute.  Here is an example of the latter:

[OperationContract]
[WebGet(UriTemplate="/products?index={index}&pageSize=
    {pageSize}")]
WineData GetProducts(int index, int pageSize);

* One important thing to note.  In the current release (SP1), if your variables are part of the query, such as above, we will do simple type conversions for you.  So, in the previous example, note that GetProducts takes in integers, but clearly the querystring parameters are strings.  We will take care of this simple conversion for you.  However, if the variables are in the path, we will not.  There is no reason for this, other than it was done for the query, not the path.  It is my understanding that support for type conversions in the path is on the list for a future release.  Just thought you might like to know.

As you can see, the UriTemplate is useful in controlling the URI.  However, there are limitations.  As my might have noticed, the template is defined for the path and querystring after the path to the svc file.  It does not provide any help for manipulating that portion of the URI.

(see this article on MSDN for more information on UriTemplates)

Given this information, we could define a UriTemplate to clean up the URI for our GetWine operation.  Perhaps we want the path to be something like this:  wine/17 (where 17 is an actual wine id).  We could simply change our code to look like this:

[OperationContract]
[WebGet(UriTemplate="wine/{wineID}",
        ResponseFormat = WebMessageFormat.Xml)]
WineData GetWine(string wineID);

The call would look like this:

image

UriTemplate Enhancements in WCF 3.5 SP1

The WCF team added some enhancements to UriTemplates when Visual Studio 2008 SP1 (and Fx 3.5 SP1) was released.  These included support for default values for parameters in paths and compound template segments.  It is simple to define a default value.  Simply set the variable to the default value with an ‘=’.  Remember that you cannot assign defaults to variables in the query portion of the template.  Here is what our example would look like, setting the default value of wineID = 22:

[OperationContract]
[WebGet(UriTemplate="wine/{wineID=22}",
        ResponseFormat = WebMessageFormat.Xml)]
WineData GetWine(string wineID);

You can now omit the id segment of the URI like this:

image

Compound template segments allow you to combine both variables and literals within one segment.  If you are familiar with ADO.NET Data Services, you will note that the ID for entities uses compound template segments.  The IDs look like this:  Entity(id).  ADO.NET Data Services runs on WCF and the webHttpBinding, so you might rightly assume that this functionality was added for this purpose.  However, you can take advantage as well.  If I wanted to implement a similar ID scheme, it would look like this:

[OperationContract]
[WebGet(UriTemplate="wine({wineID})", ResponseFormat =
        WebMessageFormat.Xml)]
WineData GetWine(string wineID);

Here is what it looks like:

image

Completely Controlling the URI

All of the examples we have seen so far only allow us to template the URI after the path to the svc file.  If you want to take full control of the URI, you have to do some kind of URL Rewriting.  There are a variety of means to accomplish this.  ScottGu’s blog post Tip/Trick: Url Rewriting with ASP.NET illustrates 4 approaches, including implementing HttpModules, using Request.PathInfo and taking advantage of 3rd party ISAPI filters.  John Flanders’ blog post Using WCF WebHttpBinding and WebGet with nicer Urls illustrates how you can build an HttpModule with IIS7 for URL Rewriting.  In this post, I will illustrate how you can take advantage of the new URL Rewrite Module for IIS 7.0 CTP1.  This module allows you to simply add rules that define pattern matches (either Regular Expressions or WildCards) and rewrite to a specified URL pattern.  Actually the module does more than that.  To see the full functionality, check out Bill Staples’ blog post on the subject.

For our purposes, we simply want to define a pattern for the incoming URL using Regular Expressions.  This pattern will represent what we want the "Hackable" URI to look like.  We will then take this URI and rewrite it to the actual path that we defined earlier ([protocol]://[hostname][:port][/path][/svc filename]).  An example will probably best illustrate our goal and how we can accomplish it.  Taking the last example we had, the URI looked like this:

image

As my annotations clearly point out, we may not want the ".svc" as part of our URI.  That is really a technical implementation detail and does not really have a place in the "hackable" URI.  So, for this simple example I will illustrate how we can use the Url Rewrite Module to remove the svc extension.  Here is the process:

  1. Make sure you have installed Vista SP1
  2. Make sure you have installed the CTP of the Rewrite Module
  3. Open IIS 7
  4. Navigate to your application and dbl-click on the URL Rewrite Module Icon
    image
  5. Click on add rule in the upper right hand corner
  6. Fill out the form with the following data (we will describe the patterns in detail in a moment):
    1. Name:                       Remove Svc Extension (or any name you want)
    2. Requested URL:         Matches the pattern
    3. Using:                       Regular Expressions
    4. Pattern:                    ^([0-9a-zA-Z\-]+)/([0-9a-zA-Z\-\.\/\(\)]+)
    5. Ignore Case:             Checked
    6. Action Type:              Rewrite
    7. Rewrite URL:             {R:1}.svc/{R:2}
    8. Append QueryString   Checked
  7. Click Apply
    image

You are ready to go.  But before we test it, I want to dissect the pattern we used for matching.  The match pattern was:

^([0-9a-zA-Z\-]+)/([0-9a-zA-Z\-\.\/\(\)]+)

Here is the breakdown of the pattern:

  • The "^" indicates the beginning of the line or string
  • The parenthesis "()" allow you to define a numbered capture group, meaning that you can reference everything inside the parens later by index.  In our example, we have 2 numbered capture groups 1 and 2.  You refer back to these later with the syntax: {R:1} and {R:2}
  • The pattern [0-9a-zA-Z\-]+ indicates any character in 0-9, lowercase a-z, uppercase A-Z or "-", one or more repetitions.
  • The / is a straight match to a slash "/".  In other words, the first named capture group will capture 0-9,a-z, A-Z and "-" prior to the first "/" and you will be able to reference them with {R:1}
  • Then we have another named capture group
  • The pattern [0-9a-zA-Z\-\.\/\(\)] matches any character in 0-9, lowercase a-z, uppercase A-Z or "-", ".", "/", "(", ")", one or more repetitions.

The rewrite URL is simply everything in the first named capture group (everything prior to the first /) which should be the svc file, without the svc extension.  We then append an svc extension and a slash.  We then append everything in the named capture group. 

Let’s see it in action.  Here is our new svc-less request:

image

Eliminating the ".svc" extension is just the tip of the iceburg.  Hopefully, you can see how you can take full control of the URI.

“Oslo” Interviews on Channel 9

“Oslo” Interviews on Channel 9

As you know “Oslo” is the family of new technologies that enable data-driven development and execution of services and applications.  There will be several sessions at PDC discussing the technologies involved in “Oslo” in much detail.  In the interim, we have published two interviews on Channel 9. 


 


In these interviews, our very own Ron Jacobs talks to David Chappell and Jon Flanders to understand their perspectives on “Oslo” and how we can prepare for the road ahead.  If you’re wondering about “Oslo” tools, language and repository and want to build your apps today to prepare for the road ahead, you’d then definitely want to watch these videos.


 


Enjoy!


Marjan Kalantar