locked
Where's the documentation for Microsoft.Data.Edm and Microsoft.Data.OData? RRS feed

  • Question

  • I have them both built under .NET 3.5 (they are checked in to codeplex to build under 3.5). But how do I use them?

    1. If I have a Url (and optionally a username & password), how do I get the EDM for the metadata?
    2. Is there anything in the API to help me build a url for a select?
    3. If I have a select Url (and optionally a username & password), how do I pass that and get back the data it returns?

    thanks - dave


    Who will win The International Collegiate Programming Championships?

    Monday, July 23, 2012 5:03 PM

Answers

  • Hi,

    We do have API level documentation (that's up on MSDN), but we don't have the walkthroughs just yet. There's a very simple one here: http://blogs.msdn.com/b/astoriateam/archive/2011/10/14/introducing-the-odata-library.aspx

    Let me try to describe the basics at least :-)

    - To read or write a message with ODL, you will need to implement the IODataRequestMessage or IODataResponseMessage interfaces (you might only need one, that depends on the scenario). We don't provide stock implementations of these. But they are basically a simple HTTP request/response interfaces.

    - ODL currently doesn't handle anything in the URL space, it only deals with the payloads. There's some early work in the ODataLib Contrib project around URL parsing if you're interested, but it's currently very alpha level.

    - To read you create ODataMessageReader over the message interface. To write you create ODataMessageWriter. The read and write APIs should be symmetrical (ReadProperty versus WriteProperty and so on).

    - What you read or write is represented using the OData OM. So classes like ODataProperty, ODataEntry, ODataFeed and so on.

    - Because we don't provider the message interface implementations we don't actually deal with any networking stack directly. So that part is completely up to you. So for example if you need to perform auth, you will need to implement that in your message interfaces somehow. On the other hand using existing .NET networking stacks to implement the message interfaces tends to be really simple.

    To answer your questions:

    1. Send a GET request to the URL (your own code, ODL doesn't do networking as mentioned above). Once you get the response create the IODataResponseMessage over it. Create ODataMessageReader over that interface. Call ReadMetadataDocument on the reader. This returns IEdmModel which is the EdmLib OM for the metadata (also can be used later on in other reading to guide the payload readers).

    2. Currently there's only very small helper in ODL to build URLs. There is ODataUriUtils class which provides methods to write and read URL literals (so for example if you need to construct a filter with a number literal you would use it to convert the number value into the literal format used in the URL). So there's nothing to help you build select query options currently.

    3. Send the GET request for that URL (again using your own code). Get the response and create IODataResponseMessage over it. Create ODataMessageReader over that (ideally passing the matching IEdmModel). Assuming the response is a feed, call CreateODataFeedReader. Use the returned ODataReader to read the payload (the above blog post has a sample of this).

    Feel free to ask question about it here. It's easier for me to answer whatever you have trouble with than to try to come up with a write-up to describe all of that.

    Thanks,


    Vitek Karas [MSFT]

    Monday, July 23, 2012 6:14 PM
    Moderator

All replies

  • Hi,

    We do have API level documentation (that's up on MSDN), but we don't have the walkthroughs just yet. There's a very simple one here: http://blogs.msdn.com/b/astoriateam/archive/2011/10/14/introducing-the-odata-library.aspx

    Let me try to describe the basics at least :-)

    - To read or write a message with ODL, you will need to implement the IODataRequestMessage or IODataResponseMessage interfaces (you might only need one, that depends on the scenario). We don't provide stock implementations of these. But they are basically a simple HTTP request/response interfaces.

    - ODL currently doesn't handle anything in the URL space, it only deals with the payloads. There's some early work in the ODataLib Contrib project around URL parsing if you're interested, but it's currently very alpha level.

    - To read you create ODataMessageReader over the message interface. To write you create ODataMessageWriter. The read and write APIs should be symmetrical (ReadProperty versus WriteProperty and so on).

    - What you read or write is represented using the OData OM. So classes like ODataProperty, ODataEntry, ODataFeed and so on.

    - Because we don't provider the message interface implementations we don't actually deal with any networking stack directly. So that part is completely up to you. So for example if you need to perform auth, you will need to implement that in your message interfaces somehow. On the other hand using existing .NET networking stacks to implement the message interfaces tends to be really simple.

    To answer your questions:

    1. Send a GET request to the URL (your own code, ODL doesn't do networking as mentioned above). Once you get the response create the IODataResponseMessage over it. Create ODataMessageReader over that interface. Call ReadMetadataDocument on the reader. This returns IEdmModel which is the EdmLib OM for the metadata (also can be used later on in other reading to guide the payload readers).

    2. Currently there's only very small helper in ODL to build URLs. There is ODataUriUtils class which provides methods to write and read URL literals (so for example if you need to construct a filter with a number literal you would use it to convert the number value into the literal format used in the URL). So there's nothing to help you build select query options currently.

    3. Send the GET request for that URL (again using your own code). Get the response and create IODataResponseMessage over it. Create ODataMessageReader over that (ideally passing the matching IEdmModel). Assuming the response is a feed, call CreateODataFeedReader. Use the returned ODataReader to read the payload (the above blog post has a sample of this).

    Feel free to ask question about it here. It's easier for me to answer whatever you have trouble with than to try to come up with a write-up to describe all of that.

    Thanks,


    Vitek Karas [MSFT]

    Monday, July 23, 2012 6:14 PM
    Moderator
  • Hi Vitek;

    Thank you - this helps. I think our posts crossed as I posted one as this came in.

    One thing I'm unclear on. You say above I need to do the http GET and then feed that metadata to the OData library. But I am calling EdmxReader.TryParse() passing it a url and getting back an IEdmModel. And that works fine.

    ??? - thanks - dave


    Who will win The International Collegiate Programming Championships?

    Monday, July 23, 2012 6:32 PM
  • Hi,

    That will work most of the time as well. There are couple of small things which ReadMetadataDocument does on top of it (you can look into the source code after all).

    - Versioning from the headers (ODL reads DataServiceVersion header and applies it as appropriate).

    - Preprocessing the OData specific annotations (like the Entity Property Mapping and couple of others). This step also means additional validation of the model for OData specific issues.

    So overall we still suggest using the ReadMetadataDocument over TryParse.

    Thanks,


    Vitek Karas [MSFT]

    Monday, July 23, 2012 7:17 PM
    Moderator
  • Also, do you have an example that uses XML instead of JSON for reading data? I find XML a lot easier to work with (I can use XDocument).

    thanks - dave


    Who will win The International Collegiate Programming Championships?

    Monday, July 23, 2012 8:47 PM
  • Hi;

    Where can I find the class HTTPClientRequestMessage? It's not in the 3 projects you told me to get and a Bing search finds 6 pages referencing it, but none say where the code is.

    ??? - thanks - dave


    Who will win The International Collegiate Programming Championships?

    Monday, July 23, 2012 8:59 PM
  • Hi,

    Sorry - I don't understand the XML versus JSON question. If you use ODL the difference is almost completely hidden from you, the API behavior of ODL will be the same (or very close being the same) no matter whether the payload was ATOM or JSON. If you want ATOM response just modify the Accept header sent with the request to request application/atom+xml instead of application/json;odata=verbose.

    The HTTPClientRequest message which is just a very rough sample (please don't use it directly in any production code, make sure you review it and so on) is part of the sample on the blog post http://blogs.msdn.com/b/astoriateam/archive/2011/10/14/introducing-the-odata-library.aspx. At the very end of the blog post is a zip file with the sample itself.

    Thanks,


    Vitek Karas [MSFT]

    Tuesday, July 24, 2012 9:21 AM
    Moderator
  • Hi Vitek;

    I downloaded the sample in the zip file and that does have the class HTTPClientRequestMessage. However, the project has a reference to Microsoft.Data.Services and Microsoft.Data.Services.Client. I can find a .net 4.0 bin download but not a 3.5 bin or the sources anywhere. Where can I find that?

    thanks - dave


    Who will win The International Collegiate Programming Championships?

    Tuesday, July 24, 2012 4:07 PM
  • We didn't release WCF DS 5.0 (which is what Microsoft.Data.Services and Microsoft.Data.Services.Client is) for .NET 3.5. The Microsoft.Data.Service.Client source code should be available on codeplex (Although I'm not sure which version), but the Microsoft.Data.Services has not been open sourced yet.

    In any case, you should not need it to reuse the ODL related code, the sample uses it to implement the "other" end (so when the sample shows how to consume an OData feed, it uses WCF DS Server to serve the feed and so on).

    Thanks,


    Vitek Karas [MSFT]

    Tuesday, July 24, 2012 5:49 PM
    Moderator