Scott On Writing.NET : Web Services

Returning Dynamic Types from an Ajax Web Service Using C# 4.0

Scott Mitchell — Tue, 26 Oct 2010 02:40:12 GMT

Over at 4Guys I’m authoring a series of articles showing different techniques for accessing server-side data from client script. The most recent installment (Part 2) shows how to provide server-side data through the use of an Ajax Web Service and how to consume that data using either a proxy class created by the ASP.NET Ajax Library or by communicating with the Ajax Web Service directly using jQuery.

When returning data from a service it’s not uncommon to create a specialized Data Transfer Object (or DTO), and in Part 2 I create two such DTO classes. Here’s the basic design pattern:

Create a DTO class that has properties that model the data you wan to return. For instance, the following DTO class can be used to transmit CategoryID, CategoryName, and Description information about one or more categories.

public class CategoryDTO
{
    public int CategoryID { get; set; }
    public string CategoryName { get; set; }
    public string Description { get; set; }
}

In the service, get the data of interest from your object layer. In the demo for this article series I use Linq-To-Sql as my data access layer and object model. Here is code from the Ajax Web Service’s GetCategories method that retrieves information about the categories in the system:

[WebMethod]
public CategoryDTO[] GetCategories()
{
    using (var dbContext = new NorthwindDataContext())
    {
        var results = from category in dbContext.Categories
                        orderby category.CategoryName
                        select category;

        ...
    }
}

Now the results need to be mapped from the domain object to the DTO. This can be done manually or by using a library like AutoMapper. In the above example, we would iterate through the results to create an array of CategoryDTO objects, which is what would be returned.

If you are using C# 4.0 you can choose to live in a looser-typed world. Rather than having the Ajax Web Service return a strongly-typed value (namely, an array of CategoryDTO objects) you could instead opt to have a more ethereal return type – dynamic! Having a return type of dynamic allows you to return an anonymous type, meaning you don’t need to create a DTO nor do you need to map the domain object to the DTO. Instead, you’d just create an anonymous type, like so:

[WebMethod]
public dynamic GetCategories()
{
    using (var dbContext = new NorthwindDataContext())
    {
        var results = from category in dbContext.Categories
                        orderby category.CategoryName
                        select new
                        {
                            category.CategoryID,
                            category.CategoryName,
                            category.Description
                        };

        return results.ToArray();
    }
}

Note the dynamic keyword as the method’s return type. Also note that results is a query that returns an enumeration of anonymous types, each of which has three properties – CategoryID, CategoryName, and Description. The call to the ToArray method executes the query and returns the array of anonymous types as the method’s output. Because the anonymous type’s properties. The client-side script calling this method can work with the returned anonymous type using the exact same code as with the strongly-typed return type.

Happy Programming!

Adding a RESTful Service to My Boggle Solver

Scott Mitchell — Fri, 10 Sep 2010 22:47:20 GMT

This blog post has been deprecated. Please see Updating My Online Boggle Solver Using jQuery Templates and WCF for an updated discussion on the solver service, the data it returns, and how to call it from a web page.

My immediate and extended family enjoys playing games, and one of our favorites is Boggle. Boggle is a word game trademarked by Parker Brothers and Hasbro that involves several players trying to find as many words as they can in a 4x4 grid of letters. At the end of the game, players compare the words they found. During this comparison I've always wondered what words we may have missed. Was there some elusive 10-letter word that no one unearthed? Did we only discover 25 solutions when there were 200 or more?

To answer these questions I created a Boggle solver web application (back in 2008) that prompts a user for the letters in the Boggle board and then recursively explores the board to locate (and display) all available solutions. This Boggle solver is available online - fuzzylogicinc.net/Boggle. My family uses it every time we get together and play Boggle. For more information on how it works and to get your hands on the code, check out my article, Creating an Online Boggle Solver.

Recently, I’ve been working on some projects that have involved creating RESTful web services using WCF. Being Friday, I decided to have a little fun and add a RESTful interface to the Boggle solver. This was actually quite easy to do and took all of 5 minutes.

Creating the Boggle Solver Service

I started by adding a new item to my website of type WCF Service, naming it Solver.svc. This created three files:

Solver.scr
ISolver.cs
Solver.cs

In the contract (ISolver.cs) I added a single method, Solve, that accepts two inputs: a string representing the board and a string indicating the minimum number of letters for a word to be considered a solution. (Boggle rules allow for words of three letters or more, but house rules only count words that are four letters or longer.) I then used the WebGet attribute to indicate that the board and length input parameters would be specified via the querystring fields BoardID and Length, and that the resulting output should be formatted as JSON.

[ServiceContract]
public interface ISolver
{
    [OperationContract]
    [WebGet(UriTemplate = "?BoardID={board}&Length={length}", ResponseFormat=WebMessageFormat.Json)]
    BoggleWordDTO[] Solve(string board, string length);
}

Note that the Solve method returns an array of BoggleWordDTO objects. This is a new class I created to represent the data to transmit from the service. This class has two properties:

Word – a string value that represents a word found in the Boggle board, and
Score – the score for that solution. According to the official rules, three and four letter words are worth 1 point, five letter words are worth 2, six letter words worth 3, seven letter words worth 5, and eight letter words and longer worth 11.

The Solve method implementation (Solver.cs) is pretty straightforward. It starts with a bit of error checking to ensure that the passed in board and letter information is kosher. Next, it creates a BoggleBoard object, specifying the minimum number of letters for a solution and the board contents. Then the BoggleBoard object’s Solve method is invoked, which performs the recursion and computes the set of solutions (as an object of type BoggleWordList). The solutions are then converted into an array of BoggleWordDTO objects, which is then returned to the client.

public BoggleWordDTO[] Solve(string board, string length)
{
    ...

    // Create the BoggleBoard
    BoggleBoard bb = new BoggleBoard(
                        letters,
                        board[0].ToString(), ..., board[15].ToString()
                    );

    // Solve the Boggle board
    var solutions = bb.Solve();

    // Populate and return an array of BoggleWordDTO objects
    return solutions
                .Select(s => new BoggleWordDTO()
                {
                    Word = s.Word,
                        Score = s.Score
                })
                .ToArray();
}

Because the service is configured to return the data using JSON, the results are serialized into a JSON array.

In addition to creating the Solver-related files and writing the code I noted, I also had to add <system.serviceModel> configuration to Web.config to permit HTTP access to the service and to enable ASP.NET compatibility. The reason I had to enable ASP.NET compatibility is because the dictionary used by the solver is a text file stored on disk, and the solver gets the path to that text file using Server.MapPath (namely, HttpContext.Current.Server.MapPath(“…”)). Without ASP.NET compatibility, HttpContext.Current is null when the service attempts to solve and then the call to Server.MapPath blows up. Also, I had to specify the Factory attribute in the <%@ ServiceHost %> directive of the Solver.svc file.

[UPDATE: 2010-09-10] Ben Amada posted a helpful comment pointing me to the existence of the HostingEnvironment.MapPath method, which does the same work as Server.MapPath but doesn’t require an HttpContext object. I updated this code accordingly. I also updated the code that cached the dictionary in memory, replacing the use of HttpContext.Current.Cache with HttpRuntime.Cache, which I probably should have been using all along. The code has been updated. Thanks, Ben!

Using the Boggle Solver Service

To use the service, just point your browser (or your code/script) to: http://fuzzylogicinc.net/Boggle/Solver.svc?BoardID=board&Length=length. The board value should be entered as a string of the characters in the Boggle board, starting from the upper left corner and reading to the right and down. For example, if you had the board:

r e i b
t m f w
i r a e
r h s t

You would use a board value of reibtmfwiraerhst. letter should be a number between 3 and 6, inclusive.

So, to find all solutions to the above board that are four or more letters, you’d visit: http://fuzzylogicinc.net/Boggle/Solver.svc?BoardID=reibtmfwiraerhst&Length=4

Doing so would return the following (abbreviated) JSON:

[{"Score":1,"Word":"amir"},{"Score":2,"Word":"amirs"},{"Score":1,"Word":"awes"},{"Score":1,"Word":"bier"},{"Score":1,"Word":"ears"},{"Score":1,"Word":"east"},...]

The above JSON represents an array of objects, where each object has two properties, Score and Word.

So how can this service be used? Well, with a bit of JavaScript you can call the service from a browser and display the results dynamically. I’ve included a rudimentary example in the download (which you can find at the end of this blog post) that prompts the user to enter the 16 characters for the board and the minimum number of letters. It then uses jQuery’s getJSON function to make a call to the service and get the data back. The JSON array is then enumerated and a series of list items are constructed, showing each solution in a bulleted list.

Here is the web page when you visit it and enter a boggle board and the minimum number of letters (but before you click the “Find All Words!” button.

Clicking the “Find All Words!” button executes the following jQuery script:

$.getJSON(
    "Solver.svc",
    {
        "BoardID": $("#board").val(),
        "Length": $("#length").val()
    },
    function (words) {
        var output = "No solutions exists!";

        if (words.length > 0) {
            output = "<h2>" + words.length + " Solutions!</h2><ul>";

            var score = 0;

            $.each(words, function (index, word) {
                score += word.Score;
                output += "<li>" + word.Word + " (" + word.Score + " points)</li>";
            });

            output += "</ul><p>Total score = " + score + " points!</p>";
        }

        $("#solutions").html(output);
    }
);

Note that the above script calls the Solver.svc service passing in the BoardID and Length querystring parameters. The textbox where the user enters the board has an id of board while the minimum letter drop-down list has an id of length. The function defined in the call is what is executed when the result comes back successfully. Here, the jQuery each function is used to enumerate the array and build up a string of HTML in a variable named output that produces a bulleted list of solutions. The total number of solutions and total number of points is also included in output. Finally, the contents of output are dumped to a <div> on the page with an id of solutions.

Here’s the page after clicking the “Find All Words!” button. Nothing fancy, of course, and not nearly as useful or eye-pleasing as the website’s results page, but it does illustrate one way you can use the Boggle Solver.svc service.

Download the Code!

You can download the complete Boggle solver engine, web application, and WCF RESTful service from http://aspnet.4guysfromrolla.com/code/BoggleSolver.zip.

Happy Programming, and Happy Boggling!

Fixing "The Following Add-Ins Failed to Load" Error in Visual Studio .NET

Scott Mitchell — Tue, 20 Sep 2005 01:35:00 GMT

I am giving a talk on Web Services this week and one technology I discuss in virtually every Web Services talk is the Web Services Enhancement (WSE) Toolkit. One of the nice things about the WSE Toolkit is that it integrates with Visual Studio .NET - right-click on the Web Service or client project and there's a WSE 2.0 Settings option in the context menu that brings up a GUI to edit the WSE-related settings. However, in running through the talk/demo code today, I noticed that my copy of VS.NET on my laptop wasn't displaying the option in the GUI.

My first attempt at fixing this was to simply uninstall and reinstall the WSE Toolkit. Upon restarting VS.NET after this process, I got a dialog box with the warning, “The Following Add-Ins Failed to Load - WSE 2.0.” Urg. I did a bit of searching and discovered that one way to fix this was to “repair” the VS.NET installation. So, off I went to the Add/Remove New Programs screen and went to the VS.NET installation screen and clicked on the Repair/Reinstall option. This prompted me for the VS.NET CDs and, about 20 minutes later, wrapped up doing whatever in the world it was doing.

Fortunately, this fixed the problem for me. I have no idea what the problem was, exactly, but opting to repair VS.NET is what ended up working for me. Hope this helps someone else in a similar situation. For those more familiar with VS.NET Add-In specifics, any guesses/ideas as to what the problem was and, perhaps, a more direct, quicker workaround?

TONIGHT: What Are .NET Web Services? Talk

Scott Mitchell — Thu, 14 Jul 2005 14:54:00 GMT

Tonight I will be presenting a talk titled What are Web Services? for the San Diego .NET User Group Beginner's SIG (a synopsis of the talk is given at the end of this post). The talk starts at 6:30 and is held in an office in Del Mar, just north of the 56 and just east of the 5. In addition to hearing me babble on about Web Services for an hour and change, there will be free pizza!!! Hope to see you there!

This talk will examine the fundamentals of Web services from a beginner's perspective, focusing on the goals of Web services and common uses of Web services in industry today. It Includes a high-level look at the core Web service standards, along with live demos illustrating how to create a Web service and client application using Visual Studio .NET.

Viewing WSE Trace Files

Scott Mitchell — Fri, 03 Dec 2004 20:13:00 GMT

One of the neat features of Microsoft's WSE Toolkit is that with the click of a button you can have all incoming and outgoing SOAP messages from a client or service recorded in trace files. These files, named by default InputTrace.webinfo and OutputTrace.webinfo, can be helpful for debugging or for gaining a deeper understanding as to the actual XML being scurried back and forth between a client and a Web service. One thing that's always irked me, though, is that these trace files are simply appended to with each run. This is fine and good, I guess, but it makes it hard to pick through these logs.

Every time I introduce WSE to my Web Services .NET students, I show them the tracing features, and have to sludge through opening the files in UltraEdit32, or Internet Explorer, and paging through the XML and finding the incoming and outgoing messages for the example we had just completed. Well, I decided enough was enough, so I spent this morning whipping up a simply WinForms application that allows you to load in trace files and view individual messages from them, one at a time, as the following screenshot illustrates (in the screnshot I am viewing just Message #9):

I also made it so that you can view the input and output XML for a given message number, as shown in the following screenshot:

If you'd like, you can download the application and complete source code (C#). I have to give a big caveat here, though: I am not an experienced WinForms developer by any stretch of the imagination, so you may find glaring UI errors, terrible design, and offensive source code. Be forewarned. I learned a lot of new things today and played around with things like isolated storage and resizing WinForm controls... things I've done zero times before, so the code may be littered with mistakes. Also, I do zero exception handling, so a missing file, or invalid permissions, or malformatted XML, and kablamo, the app's gonna bomb out on you.

Ok, enough of a caveat. Enjoy the program!

Cryptic WSE 2.0 Error (WSE032 "configuration error" and System.Net.Dns.GetHostName())

Scott Mitchell — Fri, 03 Dec 2004 02:34:00 GMT

While I was teaching my .NET Web Services class tonight I stumbled upon an esoteric error with WSE 2.0 that I had not encountered before - an error that ruined two demos of mine. I had tried the demos literally 15 minutes before class and theyh worked great. When I had a full classroom, though, it crapped out. The error message I got was the standard WSE032, saying:

An unhandled exception of type 'System.Configuration.ConfigurationException' occured in microsoft.web.services2.dll

Additional information: WSE032: There was an error loading the microsoft.web.services2 configuration section

This is a pretty common error message when something has gone awry in WSE. For example, if you are using UsernameToken authentication, but mistype any values in the Web.config file you'll get this error. What was a bit perplexing was that, (a) the demos had worked earlier, and (b) the stack trace of the error message referred to a problem with System.Net.Dns.GetHostName(). As I said, my demos bombed out, but afterwards I did a quick search on Google and found this blog entry: WSE 2.0 (sp1 & earlier) - The mistory [sic] of error code WSE032.

This blog entry had a fix for my problem. It appears that WSE uses the GetHostName() method, and this caused some problems, perhaps because my computer's wireless connection died, or my DNS entries timed out, or something. Anywho, the solution - which worked for me - was to add a line to the HOSTS file in C:\WINDOWS\system32\drivers\etc. This did the trick. Probably the most esoteric bug I've faced in my experiences with Web services.

Random (Perhaps Outdated) Web Service Tip for the Weekend

Scott Mitchell — Sun, 07 Nov 2004 02:07:00 GMT

With the Web Service Enhancement (WSE) Toolkit it is very easy to view incoming/outgoing SOAP requests - just check the “Enable Message Trace“ option in the option in the Diagnostics tab of the WSE Toolkit, and off you go. But prior to the WSE Toolkit, providing such essential debugging information was, unfortunately, not as straightforward or easy. Older books on Web services, for example, talk about using the SOAP Toolkit, from which you can create a SOAP proxy to record the incoming and outgoing SOAP messages. However, there's a much easier way, as Web service-guru Michele Leroux-Bustamante showed me 14 months ago, almost to the day: in a Web service method, add th following code to save the incoming SOAP content:

HttpContext.Current.Request.SaveAs(filePathToSaveSOAPData, true);

This will dump the incoming request to a file, including the headers (set the second parameter to False to omit the headers). Unfortunately this raw text output is not nicely indented like the WSE Toolkit output, but it provides a simple way to quickly inspect the incoming SOAP requests from the Web service.

Speaking of Michele, she'll be speaking at the ASP.NET Connections conference, which starts up with pre-session tracks tomorrow and continues throughout all next week. I mention this because I'll be there, too. Well, not inside the conference, per se, but in Vegas, at the Mandalay Bay resort. My wife's company is sending her, so I decided to tote along as a bit of a vacation (for myself). So, while my wife's toiling away in the conference sessions, learning the latest and greatest information about ASP.NET 1.x and 2.0, I'll be hitting the blackjack tables! (More accurately I'll likely be holed up in the hotel room, working on my two upcoming MSDN articles, but I promise to at least periodically fantasize about striking it rich with lady luck.)

Sample Chapter of my .NET Web Services DVD

Scott Mitchell — Tue, 12 Oct 2004 13:22:00 GMT

A few months ago I announced the release of a training DVD of mine, Beginners .NET XML Web Services 2004. This two-disc DVD covers Web Services from the ground up, showing how to create and consume Web services using Visual Studio .NET 2003 using both VB.NET and C# examples. In addition to covering the core features of Web Services - SOAP, XML serialization, WSDL, proxy classes, etc. - the DVD also explores the Web Service Enhancements (WSE), both from a high-level (Chapter 12), as well as two specific examples: UsernameToken authentication (Chapter 13) and sending attachments with DIME and WS-Attachments (Chapter 14).

If you are interested in learning more about this DVD, you can check out Chapter 14 in its entirety (all 30+ minutes), which is available along with some other sample chapters from DVPress's training DVDs at http://dvpress.com/ecom/Downloads/Sample_Clips.aspx.

One downside with the sample chapter is that in certain areas I refer to figures. Some are flashed up on the screen, but some are not. These figures - along with the complete source code for the projects I demoed - are all available on the DVDs. Speaking of which, if you enjoy the sample chapter, consider picking up a copy of the DVD, which can be purchased through DVPress's website (they accept PayPal) or Amazon.com.

Is There Anything More Self-Conscious than Watching Yourself?

Scott Mitchell — Thu, 12 Aug 2004 13:16:00 GMT

My latest “book” is out, but this time it's not a book - it's a DVD. About two and a half months ago I started talking with DVPress, a company that makes technical training DVDs, and decided to participate in creating a DVD targetted toward those interested in learning the fundamentals of .NET Web Services. I flew out to Houston at the end of May, and spent two days filming the seven or so hours of training that's on the two-disc DVD. Yesterday I received the 20 author's copies and, naturally, sat down to watch myself. The verdict? I don't like the way my voice sounds (although I already knew that).

Anywho, if you are interested in learning about .NET Web services, or know someone who is, or just want to own a DVD where yours truly is sitting there droning on for seven hours, you can pick up a copy of the DVD at Amazon.com: Beginner's .NET XML Web Services ($29.95, qualified for free shipping). The training covers the basics of Web services, looks at creating and consuming Web services with Visual Studio .NET, explores the SOAP and WSDL standards, and dives into the Web Service Enhancements, showing demos on both UsernameToken authentication and sending / receiving attachments with DIME and WS-Attachments.

Funny side story from the days of filming: the studio is in an office building, and during my filming DVPress was expanding their office space into the neighboring suite. In the other suite were a team of handy-men painting, cleaning, etc. At one point, I'm in the middle of a chapter - the lights are off, save a set of bright lights on me, there's a camera and a cameraman filming, but despite this, a handyman quietly opens the door and walks into the room. He walks behind the camera, over to the side and parallel with me, about six feet away from me (still off-camera, though). The whole time I'm still looking in the camera, delivering the lesson... well, he starts painting a window sill, and he does so half turned so that while he's painting, he's watching me with this quizical look on his face. Very surreal.

New Article on UsernameToken Authentication with the WSE 2.0 Toolkit

Scott Mitchell — Wed, 14 Jul 2004 15:19:00 GMT

The latest 4Guys article was published today, and looks at implementing UsernameToken authentication using the WSE 2.0 Toolkit. In an earlier article I wrote about the Web Service Enhancements (WSE), a set of extended Web service standards defined to help businesses implement common Web service needs not addressed by the core standards (such as security and messaging). Anywho, Microsoft has been kind enough to create a free toolkit to assist developers in implementing the WSE standards. This toolkit, called the WSE 2.0 Toolkit, was officially RTMed back at TechEd this year (which I blogged about).

The main bulk of the WSE 2.0 standards address security standards. Using WSE, one can implement secure Web services using industry-defined standards. One of the security-related standards for WSE is the UsernameToken authentication standard, which spells out how a client can send along a username and password to a Web service for purposes of authentication. This latest 4Guys article - available at http://aspnet.4guysfromrolla.com/articles/071404-1.aspx - shows how easy it is to implement this standard using the WSE 2.0 Toolkit.

This 4Guys article is the ninth part in an ongoing series titled An Extensive Examination of Web Services...