This weekend I spoke at the first Lansing Day of Dot Net in Lansing, MI. This trip was a bit different as my wife joined me for the first time.  She didn’t come for the Day of .Net, but afterwards we headed up to Mackinac Island for an anniversary trip.  She did enjoy the event though and even got to attend my session.

We got up to Lansing on Friday night after dropping out daughter off at the in-laws in Fort Wayne, Indiana.  We arrived around 6:30 pm and met up with Joe Kunk, Keith Elder, Jeff McWherter, Jeff’s wife, Vivek Joshi, Vijay Jagdale, and others at the local Kinko’s.  Somehow my wife and I got tricked into helping fold pocket-mod event schedules while we were there.  Afterwards, we went to a local Lansing event called the Festival of the Moon which as to commemorate summer nights.  It was basically just a fenced in beer garden.  We met up with Alan Stevens, his wife, and James Bender there.  We didn’t stay too long as we got a bit bored with the drunken crowd and odd choices of music by the local band.  We ended up heading across the street to a local pizza shop that offered Karaoke.  Jeff, Alan, Keith, and myself all stepped up to the mic and performed our own renditions of various tunes.  It ended being an early night since many of us had to speak in the morning. While in Lansing, my wife and I stayed with Vijay who graciously let us use a spare bedroom he had instead of paying for two nights in a hotel.  Thanks for your hospitality Vijay!

On Saturday morning we headed to the event.  I quickly met up with a number of old friends: Dave Redding, Chris Woodruff, Michael Wood, Carey Payette, Michael Eaton, Jason Follas, Patrick Foley, Josh Holmes, Jennifer Marsman, and Jay Wren.  I also got to meet Len Smith and Sam Nasr and help forge some new friendships.

Sessions

Distilling the Dynamic Language Runtime

Josh Holmes kicked off one of the first sessions with a talk on the DLR and the relevance of dynamic languages in today’s world.  Josh is a Microsoft Evangelist and an amazing speaker.  I was very surprised to see that there were only 10 attendees in his session.  I can only attribute this to the fact that he held one of the first sessions of the morning.  Originally the event was suppose to start at 9am, but a few days before, they moved the start time to 8:30.  I surmise that many people hadn’t made it to the event yet.

Josh did a great job as usual.  This session was very introductory, but it was still informative and put things into a perspective that I hadn’t quite thought of before.  Here are my notes on his session:

Languages Progression

Early Languages

More at machine level and programming against registers at a low level

Modern Languages

C++, VB

Frameworks

Java and .Net allow us to write against a framework that talks to a machine.

Looking back over the history of languages, Smalltalk and LISP are dynamic languages.  LISP is 50 years old.  Why didn’t dynamic languages take off?  Some say dynamic languages were infer.  However as we get more powerful PCs a dynamic language becomes more viable

What is a Dynamic Language

• Analogy of taking everything with camping, like running shoes, and even canoe.  Then as the trip changes, you can adjust.  If you feel like hiking, then you have your shoes.  Everything you could need is with you.
• Decisions limit options.  Make a decision to go down a long road means there aren’t options to move.
• Agility = Options, Quarterbacks have options of different receiver they can use
• Dynamic languages emphasis runtime over compile time

Dynamic typing (or duck typing)

Type can change at runtime. “If it looks like a duck and talks like a duck, then its a duck”.  Josh gave an example where at a banking company they used a 16 bit integer to store values, but as time went on, that was not enough.  It would have been nice to use a dynamic language and allow the variable to expand and adjust as needed.

Dynamic Features

Open up the types at runtime which allow you to inject new properties to existing and running classes. Add the ability to dynamically add new properties to objects.

“Trade CPU cycles for productivity” Dynamic languages are slower, but its all about the trade of ideas.

About making your life easier, not the CPUs life easier.  CPUs are getting faster, why not harness the ease for the developer and user.

Evidently, Ruby is now Josh’s favorite language.  In Ruby, one of the goals is to reduce line noise (things such as variable declarations, casting, semicolons, etc is just noise).  Strings in Ruby are mutable.

What is TDD?

Test Driven Development

Analogy of Car assembly: A car isn’t sculpted as one piece.  A car is built out of many different components. Each part of a car is designed and independently tested before it is put in place.  (However, they aren’t always tested well together).  This is a lot like unit testing.  Each unit of code should be defined and tested.

Yagni (You aint goina need it) – Don’t waste time building stuff you aren’t going to need.  If you design your tests before you write your code, then you are building specifications for how the code should work.  Anything that doesn’t have a test must be fluff.

Steps in TDD

1. Write tests based off of requirements
2. Run the tests to make sure they fails.  If a test doesn’t fail, how can it be a good test?
3. Write just enough code to pass the test.
4. Go back and write more tests (step 1), and continue down the list

The tests become the documentation for how to write the code.

Dynamic Language Initiative in .Net

CLR –> Frameworks –> DLR –> Langauges

Python was originally written in C.  Eventually there was a Java implementation of python called jython.  When IronPython came along it ended up running twice as fast as standard editions of python.

Regular Expressions can be your Friend

Vijay ran a session on Regular Expressions and since he was hosting us for the weekend, I really wanted to make sure I attended his session.  He did a great job of introducing regular expressions and what is possible with them.  He event got into ways to help circumvent text based attacks.  The only real suggestion I have on the presentation is to go over some of the differences in how regular expressions are implemented in different languages.

I was surprised at the number of people who attended and how much the audience got into the topic.  This presentation contained a lot of code and demos which really fit well with the flow of the topic.  I hope to see Vijay continue to speak at future events.

Manage Complexity with Agility

Alan Stevens gave this session which covered an Introduction to Agile and the MVC pattern.  I have never gotten to attend one of Alan’s speeches before due to other conflicts, so I was glad to be able to attend this one.  Alan did a great job.  His explanation and examples of the basics of MVC and TDD were amazing.  There is no way I could have given that good of an introduction.  I went into session knowing this material, but it was great to see things in a new light, and you could see people in the audience get that little “ah ha” look.  I look forward to catching some of his talks in the future.

My Session: Agile Project Management with Scrum

My session had a modest 30 or so attendees.  I covered project management, what is “Agile”, and gave an overview of Scrum.  The audience had a number of good questions and comments.  This was the first speech of mine that my wife attended, she commented, “You did better than I expected, not that I expected you to be bad”.  I am not sure how to take that, but I think it was meant as a complement.  I do think that I get better each time I speak, but I have a long way to go to get as good as many speakers that I see.  I had a number of people come up to me after the session to make comments and ask more about how they could apply Agile techniques at their own companies.  Many people still seem to think that these techniques cant be applied to their environment.  I hope that I can help change that perception over time.  I have some ideas for some other Agile talks, hopefully they will see the light of day and be picked up at future events.

The materials from my session can be found here: http://www.danrigsby.com/files/Presentations/AgileMgmtWithScrum.zip

Closing Thoughts

The Lansing guys did a fabulous job for their first day of .Net.  I was amazed at all of the details they put into the event such as shirts for all attendees, commemorative cups for every speaker, a local camera crew to document the event, getting the mayor of Lansing to give closing remarks, etc.  I will do my best to get on the speaker list again next year.  I am sorry for those who didn’t make the trip up, this event was well worth the time and price of gas.

After the event, Jeff McWherter hosted an afterparty at his house which he claimed took more planning than the actual event itself.  Jeff really organized a high quality afterparty.  Most of the speakers and a lot of the event attendees made it out.  There was a lot of food, even more alcohol, and most importantly many good conversations about .Net. Unfortunately, my wife and I left around 9pm.  We still had to start our anniversary trip up to Mackinac Island in the morning.

IndyPass

John Magnabosco kicked us off with the introduction.  He gave the usual announcement events, board elections, etc . John ended by asking for job announcements, but was interrupted by the famous Buck Foley.  Buck is a “Matt Foley” impersonator (the ‘van down by the river’ character played by Chris Farley on Saturday Night Live), and the actor is a ‘Database Guy’ by profession.  He brings his own flavor of humor and applies it to SQL technologies. Buck seemed to be under the impression that he was the main speaker and not Tom Pizzato who he called “Pizza-Toe”.  He winged his talk this time, but it was still humorous and set a light hearted tone for the rest of the meeting.

Tom’s talk was broken into two sections: a detailed talk about new features followed by a series of demos.  The talk mainly went over all of the new features and changes in SQL Server 2008.

Tom’s Talk

Amazing Journey

Tom has worked with SQL Server for close to 19 years.  He started his talk by taking us a down memory lane by showing some of the original disks for the first version of SQL Server back when it was just a OS2 port of Sybase.  He also  picked fun of the fact that there was a launch event for a product that has not yet been released. A few items of interest from his introduction were:

• Microsoft is still on track for a Q3 launch of SQL Server 2008, but skill couldn’t give us a more specific date yet.  The next version of SQL Server will be in 2010 (at least that is where it is planned).
• FileStream data cannot be saved to a separate machine in SQL Server 2008.  it is still limited to the machine running SQL Server 2008.  Microsoft knows this is a limitation, but they chose to just get the feature out there first.

Protect your Information

• Secure Access
  • Strong Authentication
  • Granular Authorization
  • Transparent Data Encryption (TDE)
  • External Key Management
• Protect System
  • Secure Deployment
  • Secure by default: This ones  is going to be a pain for some people.  Secure by default means everything is turned off by default.  Microsoft is taking this mind set into all of its major projects.  I have talked about this before in terms of Wcf, but we also see it in Windows Server 2008 where almost no features are installed by default.

Ensure Business Continuity

• Ensure Availability
  • Mirror your data: Automatic repair of primary from backups
  • Failover clustering
  • Replicate your data
• Minimize Downtime
  • Online Operations: More to help you keep your system up including, hot swapping CPUs while running in production
  • Add system resources
  • Reduce Recovery time
• Concurrent Access
  • Database Snapshots: Not many changes here
  • Snapshot Isolations

Predictable Response

• Optimize Performance
  • Efficient Data Storage: Finally Compression at the data and backup levels. in SP2 for SQL Server 2005, the vardecimal datatype was introduced which helped open the doors for this feature.
  • Prescriptive Guidance
• Analyze Performance
  • Data Collection: Collect reports instead of wiping them
• Predict Performance
  • Plan Freezing: Allow you to save query execution plans to xml that can be run on other machines.
  • Resource Governor: Set up resources into pools and assigned users to them.  Such as giving 70% CPU and memory to a power users and  rest to non-power users.

Reduce Management Cost

• Flexible Administration
  • Visual Management: Management Studio improvements, Powershell integration, etc.
  • Automate Operations
• Manage centrally
  • Enterprise Policies
  • Monitor Compliance
• Monitor Health
  • Management Reports
  • Performance Tuning Tools

Simplify Development

• Easy Access
  • Model Entities: Models can be built off multiple tables such as a “User” entity that spans multiple tables.  LINQ can then be used to query over this data. This is what is formally called LINQ to Entities.
  • Integrated Query: Most of the LINQ stuff is slightly slower, but it is a trade off of getting the code done faster development vs. performance.  This is also know as LINQ to SQL.
  • Comprehensive connectivity
• Program data logic
  • Time aware applications: Introduced separate Date and Time fields.
  • Pass data results
• Sync your data
  • Local data storage
  • Offline Synchronization

Store your information

• Unstructured Information
  • File Storage
  • Search Text
  • Extensible Types
• Geospatial Information
  • Spatial Standards
  • Visualize Location
• Structured information
  • Model complex hierarchies: No more need to use CTEs to recursively query data to build hierarchy trees.  The new Hierarchy data type can store these values
  • Enhanced Partitioning

Integrate and Manage data

• Build Faster
  • Connect to data
  • Cleanse Data
  • Integrate data
• Manage Efficiently
  • Efficient Data Storage
  • Mange mixed workloads
  • Streamline Aggregates
• Scalable Performance
  • DW Query Optimizations: Lots of optimizations in performance of Star joins
  • Enhanced Partitioning: Easier to align partitions with their indices.

Deliver Relevant Reports

• Author reports
  • Enhanced Designers: Licensed technology from Dundas to create better and more professional looking reports.
  • Flexible Layout: Introduced Tablixs.
• Manage reports
  • Enterprise Platform: SSRS was rewritten to not require IIS and scale better in the enterprise
  • Server-based Deployment
• Deliver reports
  • Rich Visualizations
  • Render in office
  • Share reports

Drive Actionable Insight (Analysis Services)

• Build Analytical Solutions
  • Scalable Platform
  • Prescriptive Guidance
• Extend Reach
  • Manage KPIs: How many Microsoft tools report KPIs?
  • Predictive Analysis
• Deliver Insight
  • Work in Office: Data mining add-ins for office allow you to mine and report on data directly from Office tools
  • Business view of data

Tom’s Demos

Demos were done using SQL Server 2008 CTP 6.  Tom had 9 demos to show but only got to 6 of them.  The demos were run from a custom application that had the queries and results all displayed in a custom window.  This was obviously a pre-canned set of demos or at least a pre-canned tool, but it was a great way to display these features.  I know it took a lot of time to put together,

Auditing

• Auditing performance can eat up to 10%
• Audit logs are stored in a separate file on the disk.  These files are not xml or directly human readable, but at least they can’t be queried like any other table.
• Audit logs can be maintained by setting up rollover files and file sizes

Compression

• Compression types can be set at the row or page levels

Powershell

• Only works for the relational engine
• Can right click on teh database in management studio and say “Open Powershell”
• Once in powershell you can say “dir”and get the list of database objects including being able to drill into tables, users, etc. 
• You could even run more complex Powershell queries such as the ability to get tables where row count is > 1000 like:
  • dir | where < $._RowCount -gt 1000
• You can pipe results out to HTML or other mediums

Freezing Plans

• Gives you the ability to take a query execution plan and save it to XML
• Can then specify when plan to use when executing a query

New DateTime Datatypes

• Separate Date and Time datatypes
• A new DateTimeOffset datatype supports years 0001 to 9999 as well as storing time zone information
• A new DateTime2 datatype supports years 0001 to 9999

Table Value Parameters and Merge

• This was the last feature dropped from SQL Server 2005
• A new MERGE statement allows merging of rows from multiple tables. You can choose to update matched rows, insert unmatched rows, or delete unmatched rows from the primary table.

Prizes

I know a lot of people probably only came here for the prizes, and there were some great giveaways again this year.  There was an Xbox, a 30 gig Zune, two 8 gig Zunes, and a slew of books and other swag.  As usual I didn’t win anything, even though the odds were pretty good.  But I came here for the event more than the prizes

Final Thoughts

I do miss having Bill Baker at the Birthday Bashes, but Tom has been filling in nicely. He is a good speaker, is able to answer most questions, and is very competent in his skills. He was asked some detailed questions about LINQ to SQL and LINQ to Entities that he couldn’t answer, but he wasn’t afraid to punt on them and commit to getting Joe Healy to come to talk about LINQ at a future meeting.  I am looking forward to future events at IndyPASS.

Browser and WebServer Limits: http://www.boutell.com/newfaq/misc/urllength.html

• Internet Explorer: 2,083 characters, with no more than 2,048 characters in the path portion of the URL
• Firefox: 65,536 characters show up, but longer URLs do still work even up past 100,000
• Safari: > 80,000 characters
• Opera: > 190,000 characters
• IIS: 16,384 characters, but is configurable
• Apache: 4,000 characters

Different things can happen when you go beyond these URL limits depending on the browser and web servers. It could be a “413 (Entity Too Large)” error, “414 (Request-URI Too Long)” error, the URL could be truncated, or it may just work.  However since different things can happen and your service could be consumed by any source, you have to assume the worst could happen.

By looking at just these numbers, it seems you would be pretty safe with a URL that gets up to 2,000 characters.  However, lets look at the W3C standards on this.  The HTTP specification doesn’t really set a size for the length of a URL, but it does recommend being cautious when going above 255. According to Hypertext Transfer Protocol - HTTP/1.1 section 3.2:

Servers ought to be cautious about depending on URI lengths above 255 bytes, because some older client or proxy implementations might not properly support these lengths.

So for the sake of a REST interface you should avoid setting up an interface where there is any possibility of a URL getting beyond 255.  If you are using a GET verb to request a resource via the URL you should be pretty safe.  However POSTing or PUTing an insert or update via a URL may not be the way to go unless the data size is very small.

The most important thing is to keep your interfaces consistent.  You don’t want one operation that allows an insert via the URL and another through POST data.  This just makes things confusing and less discoverable.  Especially since REST has no way to publish metadata about the operations.   You could follow standards such as these:

In general this follows “High REST” which is the more pure REST.  This dictates that the HTTP Verbs define the methods to act on the resource.

Ultimately it’s up to you how you implement the REST interface, but stay consistent, be careful about URL limits, and try to follow industry standards.

A few weeks ago Larry Clarkin came down and interviewed my friend Jeff Moser and myself for an episode of the  ThirstyDeveloper podcast on Technical Blogging.  Larry wanted to do an episode about what it takes to create a professional technical blog and why every developer should consider it.   Jeff and I have different types of blogs, and it was good to get multiple perspectives on things.

It took a few weeks, but the post editing work is done and it is available to listen to.  Overall, I think the interview went pretty well, but listen to it yourself and post your own comments about what you like, what we could do better, or anything you else you want to add.

The link to the episode is: http://thirstydeveloper.com/2008/06/11/TheThirstyDeveloper24TheBloggingEpisode.aspx

I got hit by the latest developer oriented meme trekking through the blogosphere.  My friend Michael Eaton started this one, but it has taken a life of its own.  I figured eventually someone would tag me specifically to fill this out.

Here is the trace of how this request eventually got to me:

Michael Eaton (post) -> Sarah Dutkiewicz (post) -> Jeff Blankenburg (post) -> Josh Holmes (post) –>  Larry Clarkin (post) –> me (answers below)

1. How old were you when you started programming?
I was 11.  I remember it distinctly as it was when I got my first computer, a Commodore 64.  The entire OS was BASIC driven. I loved to copy programs out of the back of Basic Magazine and “try” to get them to work.  I eventually got into RPL and some C++ in high school.

For most of my youth and through college, I considered computers and programming as a hobby.  I started college working on Pre-Med degree, but ended up settling for a Psychology degree like Jeff Blankenburg.  After school I tried to use that degree, but could barely make ends meet.  I ended up going back to school a year later to attempt to get a CS degree.  I made it all the way up to senior project, but decided to just take my knowledge and get job.  This was back in 1999 and the Internet bubble was in full swing.

2. How did you get started in programming?
I think the answer to the previous question and this blog post sum things up.

3. What was your first language?
Commodore BASIC

4. What was the first real program you wrote?
In high school I wrote a few programs.  One that I remember was for my HP 48SX calculator (loved that calculator, but it was stolen in college).  I had done most Basic up until then, but when I got this calculator I really got into RPL (Reverse Polish Lisp).  It was a fun language and quite a jump from Basic. It was a simple rock/paper/scissors game.  There were no laptops back then and paying attention in class was boring.  Instead I found it more exciting to write programs on the calculator.  Naturally I ending up writing a lot of applications for that calculator in high school.

5. What languages have you used since you started programming?
Basic, RPL (Reverse Polish Lisp), C++, Cobol, Java, Javascript, Visual Basic, C#

6. What was your first professional programming gig?
I looked for my first job for about 2 months.  With no CS degree or programming experience, it was hard to get my foot in the door.  I eventually found a job at a small aviation repair company.  I think they were looking for the cheapest developer they could find, but I was happy to get a chance to work on something and get some experience (and a paycheck).  This ob was originally just suppose to be a 6 month stint, but they tried to keep me on longer. I might have stuck around, but I was eager to work with other developers.  At this aviation shop I was the sole IT department running CAT 5 cable, building/maintaining PCs, creating a Database, setting up email, developing a client application in VB6 as a front end to the database, building a classic ASP web site, etc.  I went to Interactive Intelligence after this job and have been there ever since (8.5 years and counting).

7. If you knew then what you know now, would you have started programming?
I was born to code, and I try to live life with no regrets.  Everything that I have done in my life and the events that occurred have made me who I am today.  If I changed one event in my past, I may not be where I am today or may not have met my wife.

However, I do love to program.  Knowing what I know now, I wouldn’t have stopped developing and would have jumped right into Computer Science in college.

8. If there is one thing you learned along the way that you would tell new developers, what would it be?

1. Get involved in the community.  User groups may be over your head, but that’s good to learn from.  Or user groups may be too basic for you, but that’s good to learn from too.  Community involvement is a great way to network and help others.  It also helps you share ideas and propose issues to your network of peers.
2. Start a blog.  Even if you think you are a bad writer, you will get better.  I am a terrible writer, but it is something I am working on.  Blogs help you share knowledge, store knowledge for yourself, provide samples of your code for future employers, etc.  There are many reasons to start a blog, but every professional developer should really consider getting something out there.
3. Use a tool like Google Reader and subscribe to blogs.  One of my interview questions is: “how do you say up to date with new technologies and industry trends?”  Reading blogs is a great way to stay up to date, but manually checking dozens of web sites everyday is tedious.  RSS makes things much easier because it only pulls updates.  You can check your RSS feed many times a day, but it will check all of your blogs for updates and report it to you in one interface.  Personally I am up to around 150 blogs that I follow.  It does help to have a folder hierarchy to help organize your blog feeds though.  You can start by subscribing to this blog.

9. What’s the most fun you’ve ever had … programming?
I have a lot “most fun” days.  For the most part every day is a new “most fun” day.  In particular I like days when I can code with others.  Sitting in the back room or Ivory Tower solo programming is great, but it’s a lot of fun to program with others.

10. Who are you calling out?
I am going to hit up a few of my Indianapolis tweeps who blog:

• Aaron Lerch
• Jeff Moser
• Mike Hall
• Chad Campbell (not in Indy now, but he use to be)
• Paul Hacker
• Eric Willeke

I have a new 4 min 47 sec training webcast out over creating code snippets in Visual Studio 2005 and 2008.  The video is available through JupiterMedia and can be viewed at http://www.internet.com/video/. Just look for the "Developer Video" titled "Creating Snippets in Visual Studio".  Direct link is:

http://www.internet.com/video/?bcpid=1431564240&bclid=1433966034&bctid=1589625246

You can still create a mexHttpBinding endpoint which can be used to represent the structure of the data that the REST service understands.  You just cant really use this metadata to build a proxy client based on the REST interface. You don’t need any addition endpoints to expose the WSDL, having just a webHttpBinding endpoint is enough.  You just need to enable httpGet on the serviceMetadata (see here for more detailed information on this):

<serviceBehaviors>
    <behavior name="contactServiceBehavior">
        <serviceMetadata httpGetEnabled="true"/>
    </behavior>
</serviceBehaviors>

One common tactic to give the REST service some kind of documentation, is to have a "Documentation" or "Help" method on your service that returns a an HTML page as a Stream which describes how to work with the REST service (as seen in pictureservices).  This isn’t really metadata that can be consumed to generate a proxy class, but it is informative to other developers and consumers of your REST service.

Example

Lets look at an example of the "Documentation" method on a REST service.  This example is based on a simple contact service that holds a collection of contacts.  Some of the methods are AddContact, GetContact, UpdateContact, etc. The complete interface for the service is:

using System.Collections.Generic;
using System.IO;
using System.ServiceModel;
using System.ServiceModel.Syndication;
using System.ServiceModel.Web;

namespace Rigsby.RestDocumentation
{
    [ServiceContract]
    public interface IContactService
    {
        [OperationContract]
        [WebGet(UriTemplate = "help")]
        Stream GetDocumentation();

        [OperationContract]
        [WebGet(UriTemplate = "contacts")]
        List<Contact> GetAllContacts();

        [OperationContract]
        [WebGet(UriTemplate = "contacts/feed?format={format}",
            BodyStyle = WebMessageBodyStyle.Bare)]
        [ServiceKnownType(typeof(Atom10FeedFormatter))]
        [ServiceKnownType(typeof(Rss20FeedFormatter))]
        SyndicationFeedFormatter GetContactsFeed(string format);

        [OperationContract]
        [WebGet(UriTemplate = "contact/{contactId}")]
        Contact GetContact(string contactId);

        [OperationContract]
        [WebGet(UriTemplate = "contact/name/{name}")]
        List<Contact> GetContactByName(string name);

        [OperationContract]
        [WebGet(UriTemplate="contact/name/startswith/{startsWith}")]
        List<Contact> GetContactsWhereNameStartsWith(string startsWith);

        [OperationContract]
        [WebGet(UriTemplate = "contact/name/endsWith/{endsWith}")]
        List<Contact> GetContactsWhereNameEndsWith(string endsWith);

        [OperationContract]
        [WebGet(UriTemplate = "contact/name/contains/{contains}")]
        List<Contact> GetContactsWhereNameContains(string contains);

        [OperationContract]
        [WebInvoke(Method = "POST", UriTemplate = "contact/{name}")]
        void AddContact(string name);

        [OperationContract(Name = "AddFullContact")]
        [WebInvoke(Method = "POST", UriTemplate = "contact")]
        void AddContact(Contact contact);

        [OperationContract]
        [WebInvoke(Method="DELETE", UriTemplate = "contact/{contactId}")]
        int DeleteContact(string contactId);

        [OperationContract]
        [WebInvoke(Method = "PUT", UriTemplate = "contact/{contactId}")]
        void UpdateContact(string contactId, Contact contact);
    }
}

The operation to look at is "GetDocumentation".  This method returns a stream which will be the HTML of the documentation for the service.  The UriTemplate we are using is just "help", so the full path would just be something like "http://localhost:8080/ContactService/help".

[OperationContract]
[WebGet(UriTemplate = "help")]
Stream GetDocumentation();

public Stream GetDocumentation()
{
    MemoryStream stream = new MemoryStream();

    StreamWriter writer = new StreamWriter(stream, Encoding.UTF8);
    writer.Write(Properties.Resources.Documentation);
    writer.Flush();
    stream.Position = 0;

    WebOperationContext.Current.OutgoingResponse.ContentType = "text/html";

    return stream;
}

The HTML for this was manually hacked together, but you could write some process that looks at some custom attributes on the service to build this help file:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
<head>
    <title>Contact Service - Documentation</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <style type="text/css">
        body {margin: 0px;padding: 0px;font-family: Calibri, Tahoma, Arial;}
        .banner {padding: 5px 5px 5px 15px;background-color: Gray;color: White;}
        .content {margin: 15px;}
    </style>
</head>
<body>
    <div class="banner">
        <h1>Contact Service</h1>
    </div>
    <div class="content">
        <h2>Available Feeds</h2>
        <ul>
            <li><b>GET /contacts/feed?format={format}</b> &mdash; Returns a feed of all contacts as "rss" or "atom"</li>
        </ul>
        <h2>Available Endpoints</h2>
        <ul>
            <li><b>GET /help</b> &mdash; Displays the service documentation</li>
            <li><b>GET /contacts</b> &mdash; Returns all contacts</li>
            <li><b>GET /contact/{contactId}</b> &mdash; Returns a contact by contactId</li>
            <li><b>GET /contact/name/{name}</b> &mdash; Returns all contacts with the specified name</li>
            <li><b>GET /contact/name/startswith/{startswith}</b> &mdash; Returns all contacts whose name starts with the specified string</li>
            <li><b>GET /contact/name/endsWith/{endsWith}</b> &mdash; Returns all contacts whose name ends with the specified string</li>
            <li><b>GET /contact/name/contains/{contains}</b> &mdash; Returns all contacts whose name contains the specified string</li>

            <li><b>POST /contact/{name}</b> &mdash; Adds a new contact with the specified name (ignores POST data)</li>
            <li><b>POST /contact</b> &mdash; Adds a new contact with the POST data</li>
            <li><b>DELETE /contact/{contactId}</b> &mdash; Deletes a contact by contactId</li>
            <li><b>PUT /contact/{contactId}</b> &mdash; Updates a contact by contactId</li>
        </ul>
    </div>
</body>
</html>

You can download a complete sample of the code discussed in this article here: http://www.danrigsby.com/Files/Rigsby.RestDocumentation.zip

• JavaScriptSerializer supports anonymous types.
• JavaScriptSerializer works with plain strings so it can be easier to use.
• DataContractJsonSerializer can serialize DateTimes into UTC format.   Very important over the web!

I guess the big question I have is, do we really need both? Isn’t there a way to combine these into one serializer?

What about the act of undeprecating a class?  Do you think this is a good thing?

See these links for more information about the DataContractJsonSerializer:

• http://www.west-wind.com/WebLog/posts/218001.aspx
• http://pietschsoft.com/post/2008/02/NET-35-JSON-Serialization-using-the-DataContractJsonSerializer.aspx

So what is the this metadata?  Metadata is basically to describe how to interact with the service’s endpoints.  This includes metadata about:

1. The operations a service can perform
2. The structure of the data types that the operations work with or return
3. Definitions of all the endpoints implemented by the service and the various options needed for each such as security

By default service metadata is turned off.  This has been a problem for some people because you have to manually configure the service to publish the metadata.  This is by design because metadata can expose parts of your service you don’t want to expose.  Many services out in the wild do not want to publish metadata at all.  Personally, I am a bit torn about this.  Part of me understands why they implemented it this way, but the more common use is to expose metadata always.  It seems that the default should be metadata on, with the option to turn metadata off for the more rare occasions.  However, the WCF team really wanted it to be "secure by default", which means it needed to be turned off.  This can throw off classic WebService developers because in ASMX you needed to opt-out of exposing metadata, while WCF requires opt-in of exposing metadata.

The metadata can be used to generate proxy classes with svcutil.exe, "Add Service Reference" in Visual Studio, wcftestclient.exe, or any other program that can interpret the metadata and build proxies.  This data can also by used to pull out specific information about a service such as its’ endpoints, or simply just for reference information about the service.

Exposing Metadata

To expose metadata you need to turn on the serviceMetaData property in the service behavior that the service is implementing.  This can be done declaratively through the xml config files, or programmatically directly in your code:

Declaratively

The minimum you need is to add the serviceMetaData node to the serviceBehavior being used by the service:

<serviceBehaviors>
  <behavior name = "MetadataBehavior">
    <serviceMetadata />
  </behavior>
</serviceBehaviors>

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.serviceModel>
    <behaviors>
      <serviceBehaviors>
        <behavior name = "MetadataBehavior">
         <serviceMetadata httpGetEnabled = "true"/>
        </behavior>
      </serviceBehaviors>
    </behaviors>
    <services>
      <service name = "MyService"
               behaviorConfiguration = "MetadataBehavior">
        <host>
          <baseAddresses>
            <add baseAddress =
                 "http://localhost:8080/MyService"
                 "net.tcp://localhost:9000/MyService"/>
          </baseAddresses>
        </host>
        <endpoint address = ""
                  binding = "wsHttpBinding"
                  contract = "IMyService"/>
        <endpoint address = ""
                  binding = "netTcpBinding"
                  contract = "IMyService"/>
        <endpoint address = "net.tcp://localhost:9000/MyService/mex"
                  binding = "mexTcpBinding"
                  contract = "IMetadataExchange"/>
      </service>
    </services>
  </system.serviceModel>
</configuration>

Programmatically

Adding this in code is similar.  You need to add a ServiceMetadataBehavior object to the behaviors of the serviceHost:

ServiceHost host = new ServiceHost(
    typeof(MyService),
    new Uri("http://localhost:8080/MyService"),
    new Uri("net.tcp://localhost:9000/MyService"));

host.AddServiceEndpoint(
    typeof(IMyService),
    new WSHttpBinding(),
    "");
host.AddServiceEndpoint(
    typeof(IMyService),
    new NetTcpBinding(),
    "");
Binding mexBinding = MetadataExchangeBindings.CreateMexTcpBinding();
host.AddServiceEndpoint(
    typeof(IMetadataExchange),
    mexBinding,
    "net.tcp://localhost:9000/MyService/mex");

ServiceMetadataBehavior metadataBehavior =
    new ServiceMetadataBehavior();
metadataBehavior.HttpGetEnabled = true;
host.Description.Behaviors.Add(metadataBehavior);

Enabling the serviceMetaData property is enough to expose metadata through all binding types except http and https.  For these you have to specify "HttpGetEnabled=true" or "HttpsGetEnabled=true" depending on if you are using http or https.  You must expose at least one endpoint for http or https and declare a base address or you will get a runtime exception with HttpGetEnabled or HttpsGetEnabled enabled.

Http and Https can expose metadata simply by appending "?wsdl" to the end of the base address.  For any binding type, you need to specify a metadata binding endpoint to retrieve the metadata from.  This is done by creating an endpoint that uses the IMetadataExchange interface, a corresponding "mex" binding for the transport (more on this later), and the address where the metadata published.  You can also use an IMetadataExchange address for http and https as well, but normally the "?wsdl" site is enough.

There are a few properties of ServiceMetadata:

• ExternalMetadataLocation: A Uri that contains the location of a WSDL file, which is returned to the user in response to WSDL and MEX requests instead of the auto-generated WSDL. When this attribute is not set, the default WSDL is returned. The default is an empty string.
• HttpGetEnabled: A Boolean value that specifies whether to publish service metadata for retrieval using an HTTP/Get request. The default is false. If the httpGetUrl attribute is not specified, the address at which the metadata is published is the service address plus a "?wsdl". For example, if the service address is "http://localhost:8080/MyService", the HTTP/Get metadata address is "http://localhost:8080/MyService?wsdl". If this property is false, or the address of the service is not based on HTTP or HTTPS, “?wsdl” is ignored.
• HttpGetUrl: A Uri that specifies the address at which the metadata is published for retrieval using an HTTP/Get request.
• HttpsGetEnabled: A Boolean value that specifies whether to publish service metadata for retrieval using an HTTPS/Get request. The default is false. If the httpsGetUrl attribute is not specified, the address at which the metadata is published is the service address plus a "?wsdl". For example, if the service address is https://localhost:8080/MyService, the HTTP/Get metadata address is "https://localhost:8080/MyService?wsdl". If this property is false, or the address of the service is not based on HTTP or HTTPS, “?wsdl” is ignored.
• HttpsGetUrl: A Uri that specifies the address at which the metadata is published for retrieval using an HTTPS/Get request.

Metadata Exchange Endpoint

A metadata exchange endpoint is an endpoint that returns back the metadata about the service. You can have as many metadata exchange endpoints as you want. You could have one for each service endpoint, one that all endpoints share, or 100s that just return the same data.  Usually one metadata endpoint is sufficient, but it is common to see one for each service endpoint as well.

Like all endpoints it is comprised of the ABCs: Address, Binding, and Contract:

Address

The address is just the Uri that the endpoint can be can found.  In a metdata exchange endpoint this is commonly done by appending "mex" to the base address such as "net.tcp://localhost/MyService/mex", but you can use whatever address you choose.

Binding

There are only 4 bindings that are defined to be used as a metadata endpoint:

1. mexHttpBinding: Specifies the settings for a binding used for the WS-MetadataExchange (WS-MEX) message exchange over HTTP.
2. mexHttpsBinding: Specifies the settings for a binding used for the WS-MetadataExchange (WS-MEX) message exchange over HTTPS.
3. mexNamedPipesBinding: Specifies the settings for a binding used for the WS-MetadataExchange (WS-MEX) message exchange over named pipe.
4. mexTcpBinding: Specifies the settings for a binding used for the WS-MetadataExchange (WS-MEX) message exchange over TCP

You can use any of these in the configuration file to define metadata endpoints, such as:

<endpoint address = "net.tcp://localhost:9000/MyService/mex"
    binding = "mexTcpBinding"
    contract = "IMetadataExchange"/>

In code however, these bindings must be created through the static MetadataExchangeBindings class.  It has the following 4 methods:

• CreateMexHttpBinding: Returns a System.ServiceModel.WSHttpBinding with security disabled.
• CreateMexHttpsBinding: Returns a System.ServiceModel.WSHttpBinding that supports transport-level security.
• CreateMexNamedPipeBinding: Returns a System.ServiceModel.Channels.CustomBinding with a System.ServiceModel.Channels.NamedPipeTransportBindingElement.
• CreateMexTcpBinding: Returns a System.ServiceModel.Channels.CustomBinding with a System.ServiceModel.Channels.TcpTransportBindingElement.

You can use any of these methods in your code go generate the bindings for the corresponding transport, such as:

Binding mexBinding = MetadataExchangeBindings.CreateMexTcpBinding();
host.AddServiceEndpoint(
    typeof(IMetadataExchange),
    mexBinding,
    "net.tcp://localhost:9000/MyService/mex");

Contract

A contract is just an interface that the endpoint must follow. So, what is this IMetadataExchange interface?  It only has 3 methods:

• BeginGet: Starts an asynchronous retrieval of metadata.
• EndGet: Concludes the retrieval of metadata.
• Get: Returns the service metadata

Since BeginGet and EndGet are just an asynchronous version of Get, what does Get do?  Well, as you may have guessed, it just returns the metadata for the service.

REST and webHttpBinding

So what about REST based services using webHttpBinding?  No where is there defined a way to get metadata about it.  Well, since it is REST, there is no WSDL that defines the service and no built in way to generate metadata about it.  One common tactic is to have a "Documentation" method on your service that returns a stream of data that is an HTML page which describes how to work with the REST service.  This isn’t really metadata that can be consumed to generate a proxy class, but it is informative to other developers and consumers of your REST services.