Trying out the prerelease OData Client T4 template


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

Comments (11)

  1. What if server side OData service is in same solution?

  2. @Paul – not sure I fully follow your question. The T4 template should still work fine; you'll just need to get it hosted in Cassini or IIS Express or IIS before saving the template. (The two common times the template does its generation are on save and when you right-click the template and choose to Run Custom Tool.)

  3. Do you have a timeframe for action support, once that is complete i will most proably take a look at the t4 client?

    Does the new t4 client fully support asyncronous clients (specifically silverlight 5)?

    Disclaimer: I have not yet worked with odata (apart from looking at different demos), but we might were well use it in the future, just provide us with an easy way to migrate it with our wcf ria services (you now have better query support so we only lack some validation and "projection" of entities which hopefully the t4 templates will solve :) ).

    Until then, here are some issues I've had when I used WCF RIA Services T4 templates (we modified the code generation to create a interface and modified the servicex context to also implement our interface which just wrap the standard generated functions but with more testable function signatures). Since I have not invesigated your T4 client they might not apply, but please take and make sure you don't have the same problem:

    * Provide an API for mapping server side types to client side types (if you for example have a service function returning a List<int> and the client expose a function returning IEnumerable<int> then provide a method to get this mapping as well as to write the types. Use case:  make it is easy to write the parameter list for functions taking arguments).

    * Provide an API for looking up the default names of different serviceoperations/actions etc if they differ from the name on the service.

    * Prefer to expose interfaces instead of concreate types in the generated code (WCF RIA Services uses for example EntityQuery and EntitySet of which neither implement interfaces or can be extended).

  4. Joseph Keller says:

    What tool at you using to get syntax highlighting when editing the T4 template?

  5. Guilherme Duarte says:

    The T4 template works well, but I found a couple issues:

    – Using a entity class that inherits from an object in a different namespace may cause the entities namespace to be incorrect due to: TransformContext.EdmModel.SchemaElements.First<IEdmSchemaElement>().Namespace;

    The namespace generation should cover entities in different namespaces.

    – How to use the T4 in a LightSwitch application?

    Keep up the good work!

    Regards

  6. Joepro says:

    Is the code source for 5.X.X ever going to be published on odata.codeplex.com?

  7. Baski says:

    How do you add multiple data service references in the same project?

  8. Any time frame on support for actions?  This is a huge feature for our team and without support for actions, we're building services today using web api instead.

    Thanks,

    John

  9. If the service only allows Windows authentication, the T4 template fails with 401.

    Is it possible to add support for authentication?

  10. Richard Weeks says:

    Using IIS on Windows Server 2003 with Windows Authentication, I get the following error when saving Reference.tt:

    Error 2 Running transformation: System.Net.WebException: The remote server returned an error: (401) Unauthorized.

      at System.Net.HttpWebRequest.GetResponse()

      at Microsoft.VisualStudio.TextTemplating20721DD328B05690A90A53ED65A553E2.GeneratedTextTransformation.CodeGenerationContext.LoadEdmModelFromMetadataPath() in c:UsersusernameDocumentsVisual Studio 2010ProjectsprojectnameReference.tt:line 1199

      at Microsoft.VisualStudio.TextTemplating20721DD328B05690A90A53ED65A553E2.GeneratedTextTransformation.TransformText() in c:UsersusernameDocumentsVisual Studio 2010ProjectsprojectnameReference.tt:line 98

      at Microsoft.VisualStudio.TextTemplating.TransformationRunner.RunTransformation(TemplateProcessingSession session, String source, ITextTemplatingEngineHost host, String& result) 1 1

  11. Mike C says:

    This looks great, but I need it to support both VB.NET as well as Actions.