TL;DR

We recently prereleased an updated OData Client T4 template to NuGet. The template will codegen classes for working with OData v3 services, but full support has not been added for all v3 features.

What is the OData Client T4 template?

The OData Client T4 template is a T4 template that generates code to facilitate consumption of OData services. The template will generate a DataServiceContext and classes for each of the entity types and complex types found in the service description. The template should produce code that is functionally equivalent to the Add Service Reference experience. The T4 template provides some compelling benefits:

  • Developers can customize the T4 template to generate exactly the code they desire
  • The T4 template can be executed at build time, ensuring that service references are always fully up-to-date (and that any discrepancies cause a build error rather than a runtime error)

In this blog post, we will walk through how to obtain and use the OData Client T4 template. We will not be covering other details of T4; much of that information is available on MSDN.

OData Client T4 template walkthrough

  1. Let’s begin by creating a new Console Application project.

    image

  2. Next we need to use NuGet to get the T4 template. We can do this by right-clicking the project in the Solution Explorer and choosing Manage NuGet Packages. NOTE: You may need to get the NuGet Package Manager if you are using VS 2010.

    image

  3. In the Package Explorer window, choose Online from the left nav, ensure that the prerelease dropdown is set to Include Prerelease (not Stable Only), and search for Microsoft.Data.Services.Client.T4. You should see the OData Client T4 package appear; click the Install button to install the package.

    image

  4. When the OData Client T4 package has been added to the project, you should see a file called Reference.tt appear in the Solution Explorer. (NOTE: It’s perfectly fine at this point to change the name of the file to something more meaningful for your project.) Expand Reference.tt using the caret to the left of the file and double-click to open Reference.cs. Note that the contents of Reference.cs were generated from the T4 template and that they provide further instructions on how to use the template.

    image

  5. Double-click Reference.tt to open the T4 template. On line 30, add the following: MetadataUri = http://odata.netflix.com/Catalog/$metadata;. NOTE: The T4 template does not currently support actions; if you specify a $metadata that contains actions, code generation will fail.

  6. image

  7. Save Reference.tt and expand Reference.cs in the Solution Explorer to see the newly generated classes. (NOTE: If you’re using VS 2010, you’ll need to open Reference.cs and browse the code in the file.

    image

  8. Finally, add the following code to Program.cs.

    image

  9. Press Ctrl+F5 to see the result.

    image

Why should I use the T4 template?

Currently the Add Service Reference and DataSvcUtil experiences are both based on a DLL that does not allow for customizable code generation. We believe that in the future both of these experiences will use the T4 template internally, with the hope that you would be able to customize the output of either experience. (Imagine the simplicity of ASR with the power of T4!) To do that, we need to get the T4 template to a quality level equal to or better than the ASR experience.

Feedback, please!

We’d love to hear from you! Specifically, we would really benefit from answers to the following questions:

  • Did the T4 template work for you? Why or why not?
  • What customizability should be easier in the T4 template?
  • Do you use DataSvcUtil today? For what reason?
  • If you only use DataSvcUtil for msbuild chaining, could you chain a T4 template instead?
  • Do you want the T4 template to generate C# or VB.NET?

Thanks,
The WCF Data Services Team