One of the last things I figured out to include in my Pluralsight course “Building ASP.NET Web API OData Services” (which should be out in a week or two – all done, just waiting for the editorial process to complete) was how to consume my Web API OData services with Breeze.js.
So here is a quick walkthrough so others can just take it by the numbers.
Step 1: Create your Web API Project
File > New Project, Web category, MVC 4 Application, select Web API project type.
Delete the ValuesController that it puts in the \Controllers folder.
Step 2: Add the OData NuGet
Right click on the project in Solution Explorer, find Manage NuGet Packages.
Search for OData and find the ASP.NET Web API OData package.
Step 3: Define a Data Model
I’m gonna use the venerable Northwind Customers table here to keep it simple. Add a connection string to your web.config:
Add a Customers class to the Model folder:
And a NorthwindDbContext class (Entity Framework code first approach – could use DB First or any model you want).
Step 4: Define an EDM
Open the App_Start folder in the project, open WebApiConfig.cs. Add a helper method to define an Entity Data Model:
The ODataConventionModelBuilder just needs to know the collections you want to expose. It will reflect on the types, and declare all their properties in the EDM with corresponding EDM types, will follow navigation properties to related entities and declare those, and will infer what the entity keys are.
IMPORTANT: Note line 5 – you need to make sure the namespace of the EDM matches the namespace your entity types are contained in.
Step 5: Add an OData Route
In the Register method, add an OData route for your EDM (line 3 below):
The MapODataRoute extension method takes three arguments: a name for the route, a prefix off the site root address where you can get to the EDM model you will expose, and the EDM model itself.
Step 6: Create an EntitySetController
Add a project folder called ODataControllers. Add a class in there called CustomersController, with a base class of EntitySetController<Customer,string>. Add a Get method to it that uses the NorthwindDbContext to return Customers:
Note the [Queryable] attribute on the Get method – this in combination with the IQueryable return type is what enables OData query syntax. The EntitySetController takes care of making sure the OData formatter is used instead of the default JSON formatter, as well as taking care of mapping OData routing scheme to this controller. The default OData format is JSON-Light (as opposed to JSON-Verbose or ATOM XML).
At this point you have a working OData service. You should be able to hit it in the browser with an address of /odata/Customers and you will get back the customers in the default JSON-Light format. If you want ATOM or JSON-Verbose, you will need to use a tool like Fiddler where you can control the headers.
Step 7: Add DataJS and Breeze.js through NuGet
Go back into Manage NuGet Packages from Solution Explorer and search for Breeze. Select the Breeze for ASP.NET Web Api Projects package and install. Then do the same to find and install DataJS.
Step 8: Create an HTML page + JS with JQuery, Knockout, Q, and Breeze
Go into the Views folder of your Web project and find the /Home/Index.cshtml file. Clear out all the HTML in there and add the following scripts to the top (Note: you can do this by dragging and dropping the script file from the /scripts folder (you may need to update the JQuery and Knockout NuGet packages in your project to match these versions).
Next we need a simple view model that we will data bind to from our HTML, declared inside the script block:
Next the code that calls the load and sets up the data binding with Knockout at the end of our script block, inside the JQuery ready function:
Next some simple Knockout bound HTML to render the customers (outside the script block obviously):
Step 9: Query Away!
Now all we have to do is flesh out our load method in the view model. All we need to do is form a query and execute it with the Breeze EntityManager, putting the results where we want them – in this case I loop over the results in a success callback function, pushing them into my observable array in my view model. The really cool thing is that Breeze takes care of downloading the OData metadata for the Entity Data Model and automatically creates observable types for the data objects, so the individual objects I am adding into my array are data binding friendly JS types with observable properties.
We can now run and we should get all customers:
The other cool thing is that now we can start formulating more complicated LINQ-like queries with Breeze. instead of just asking for all customers above, we could change it to ask for customers who’s company name starts with B and order by the CustomerID. Just change line 2 above to:
Please check out my Pluralsight Course “Building ASP.NET Web API OData Services” (due out by end of February) for the full story on Web API and OData.
You can download the full source code for this sample here.