Back in April, Microsoft released the fourth preview of WCF Web API on CodePlex. The intent of the WCF Web API is to make it easier to expose application data and services over HTTP. I’ve seen a lot of people throw in the REST descriptor but I’m not ready to go there yet.
I’ve spent the last couple of weeks playing with the WCF Web API and I’ve decided to put what I’ve learned out there for others. I’m imagining a series of posts but we’ll have to see where my schedule allows me to go.
In this first post, I want to basically put down the steps that I used to get started; consider this a step above the traditional Hello World program.
It’s all about the data
To get started, I first needed something to serve up. There is always the typical Northwind or AdventureWorks database that everyone is probably already familiar with. Instead, I went for something different. Shawn Wildermuth has been kind enough to to make available a database of XBox games. I’m running SQL Server 2008 so I grabbed the appropriate zip file and attached the database that is contained within it.
Next I need a host. A WCF service can be hosted within a number of application. I going to use an ASP.NET MVC 3 Application.
As long as I’m playing with new tech, I’m going to use the Code First features of Entity Framework 4. If you’re following along at home and Entity Framework isn’t already installed, you can get it via NuGet. The package name is EntityFramework.
The next thing is to create some classes that EF will use to expose the data in the Xbox games database. I’ll create three: Game, Genre and Rating and put them in the Models folder. This seemed like a good enough place to store them for now. I can always move them later.
public class Game
{public int Id { get; set; }
public string Description { get; set; }
public string Developer { get; set; }
public Genre Genre { get; set; }public string Name { get; set; }
public decimal? Price { get; set; }
public string Publisher { get; set; }
public Rating Rating { get; set; } public DateTime? ReleaseDate { get; set; }}
public class Genre
{public int Id { get; set; }
public string Name { get; set; }
}
public class Rating
{public int Id { get; set; }
public string Name { get; set; }
}
The data is accessed through an instance of DbContext. Mine looks like this:
public class XBoxGames : DbContext
{ public DbSet<Game> Games { get; set; } public DbSet<Genre> Genres { get; set; } public DbSet<Rating> Ratings { get; set; }protected override void OnModelCreating(DbModelBuilder modelBuilder)
{ base.OnModelCreating(modelBuilder);modelBuilder.Entity<Genre>().ToTable("Genres", "SimpleGames");
modelBuilder.Entity<Genre>().HasKey(g => g.Id);
modelBuilder.Entity<Genre>().Property(g => g.Id).HasColumnName("GenreID");modelBuilder.Entity<Rating>().ToTable("Ratings", "SimpleGames");
modelBuilder.Entity<Rating>().HasKey(g => g.Id);
modelBuilder.Entity<Rating>().Property(r => r.Id).HasColumnName("RatingID");modelBuilder.Entity<Game>().ToTable("Games", "SimpleGames");
modelBuilder.Entity<Game>().HasKey(g => g.Id);
modelBuilder.Entity<Game>().Property(g => g.Id).HasColumnName("GameID");modelBuilder.Entity<Game>()
.HasOptional(g => g.Genre)
.WithMany()
.Map(m => m.MapKey("Genre"));modelBuilder.Entity<Game>()
.HasOptional(g => g.Rating)
.WithMany()
.Map(m=>m.MapKey("Rating"));}
}
The three properties Games, Genres and Ratings are used to access and manipulate the data using Linq. The OnModelCreating() override is the key to the Code First implementation. This method contains the mapping of the tables to the classes and defines the relationships between the tables, in terms of the classes.
The last item is to tell Entity Framework where to find the database. I’ve added the following connection string to the web.config file:
<connectionStrings>
<add name="XBoxGames"
connectionString="data source=.\SQLEXPRESS; Integrated Security=SSPI; database=XBoxGames"
providerName="System.Data.SqlClient"/>
</connectionStrings>
Resources
The next step is to expose the game data over HTTP. If you were wondering when I’d get to WCF Web API, well, that’s now.
Like EntityFramework, WCF Web API can be added to the project using NuGet. The package to install is WebApi.All
The nice thing about using NuGet to add libraries to your solution is that it will automatically pickup any dependencies that are required. I needed four.
I’ve decided to create a resource called GamesResource and expose it over HTTP.
[ServiceContract]
public class GamesResource
{[WebGet(UriTemplate = "")]
public List<Game> GetGames() {using (var gamesRepository = new XBoxGames())
{ return gamesRepository.Games
.AsNoTracking()
.OrderBy(g => g.Id)
.Include("Genre") .Include("Rating").ToList();
}
}
}
Accessing this resource will return a list of all the games, sorted by the game ID.
Note: Returning the entire table via HTTP is probably a very unlikely scenario, if for no other reason than you are stressing your network and server resources. The most common mitigation is to provide either filtering or paging capabilities. I plan to add paging in a future post.
The last thing that I have to do is add some configuration that exposes the new GamesResource. Within Global.asax.cs, I’ve changed the RegisterRoutes() method to:
public static void RegisterRoutes(RouteCollection routes)
{ routes.IgnoreRoute("{resource}.axd/{*pathInfo}"); routes.MapServiceRoute<GamesResource>("games");routes.MapRoute(
"Default", // Route name
"{controller}/{action}/{id}", // URL with parameters
new { controller = "Home", action = "Index", id = UrlParameter.Optional } // Parameter defaults
);
}
The call to MapServiceRoute() exposes the GamesResource as an Uri whose path starts with “games”. For example, the Uri http://localhost/games would be directed to our GetGames() method within GamesResource.
Starting the site with F5 and navigating to the games resource (for me is: http://localhost:1064/MessinWebApi/games) displays the list of games, encoded using Xml!
Returning a single game
I now want to allow the consumer of my service to fetch a single game using an Uri similar to http://localhost/games/12. This is easy and built into the WCF Web API via the UriTemplate parameter of the WebGet Attribute. This will look familiar if you’ve worked with ASP.Net MVC routing.
I’m going to add a new method to GamesResource called GetSingleGame():
[WebGet(UriTemplate = "{id}")]public Game GetSingleGame(string id)
{using (var gamesRepository = new XBoxGames())
{int idToFind = int.Parse(id);
return gamesRepository.Games
.AsNoTracking()
.Include("Genre") .Include("Rating").Where(g => g.Id == idToFind)
.FirstOrDefault();
}
}
GetSingleGame() is very similar to GetGames() with the exception that I have defined a token called {id} within the UriTemplate property of the WebGet attribute and I’ve added a parameter to GetSingleGame() to receive the value. The WCF Web API infrastructure will handle parsing the incoming request to get the ID and making the appropriate call to GetSingleGame().
When put into motion, a request for the game with an ID of 12 (http://localhost:1064/MessinWebApi/games/12) results in the following Xml:
This is just the “tip of the iceberg” for WCF Web Api. There is a very extensible pipeline built into the framework. I plan to explore some of these features in future posts.
No comments:
Post a Comment