{"id":3335,"date":"2019-07-27T23:46:49","date_gmt":"2019-07-28T06:46:49","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/odata\/?p=3335"},"modified":"2019-07-28T22:32:44","modified_gmt":"2019-07-29T05:32:44","slug":"integrating-cosmos-db-with-odata-part-1","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/integrating-cosmos-db-with-odata-part-1\/","title":{"rendered":"Integrating Cosmos DB with OData (Part 1)"},"content":{"rendered":"

We talked in previous articles about the pluggability of OData with any storage technology regardless of its schema, whether it\u2019s a SQL-based storage, NoSQL, In-Memory or simply a file on a hard-drive.<\/p>\n

This power of OData enables developers to work with powerful, planet-scale storage technologies such as Cosmos DB.<\/p>\n

In this article we are going to deep dive into one of three ways you can integrate Cosmos DB with OData but before we start, let\u2019s talk a little bit about Cosmos DB, it\u2019s capabilities and why it\u2019s important to be able to expose that storage powerful through an API with OData.<\/p>\n

 <\/p>\n

What is Cosmos DB?<\/h3>\n

Azure Cosmos DB is Microsoft’s globally distributed, multi-model database service. It enables you to elastically and independently scale throughput and storage across any number of Azure regions worldwide. You can elastically scale throughput and storage, and take advantage of fast, single-digit-millisecond data access using your favorite API including SQL, MongoDB, Cassandra, Tables, or Gremlin.<\/p>\n

Cosmos DB is a perfect solution for the hot category of storage, specifically data that needs to be accessed frequently and be retrieved as fast as possible.<\/p>\n

 <\/p>\n

Cosmos DB with OData<\/h3>\n

When planning to integrate Cosmos DB with OData, there are three different ways you can follow to accomplish that level of integration based on your preference and whichever model fits the application you\u2019re developing.<\/p>\n

If you don\u2019t have any specific preference when it comes to integrating Cosmos DB with OData, I highly recommend you try them all, and judge for yourself which approach is easier and best fits your needs.<\/p>\n

 <\/p>\n

Let\u2019s talk about the first of these approaches in this article.<\/p>\n

 <\/p>\n

First Approach: Pre-Built ASP.NET Core Solution<\/h3>\n

Cosmos DB in Azure Portal comes with some amazing options that enable you to download a full solution with full CRUD operations and UI to interact with Cosmos DB.<\/p>\n

In order for you to do that, go to your Azure portal and create a new Cosmos DB resource as follows:<\/p>\n

 <\/p>\n

Setting up Cosmos DB<\/h3>\n
    \n
  1. Click on \u201cCreate a resource\u201d button at the top left corner in your Azure Portal:<\/li>\n<\/ol>\n

    \"\"<\/p>\n

      \n
    1. Search for Azure Cosmos DB, then click \u201cCreate\u201d button.<\/li>\n<\/ol>\n

      \"\"<\/p>\n

        \n
      1. When you click the \u201cCreate\u201d button, you will be presented with a bunch of options to select which API you\u2019d like to choose to interact with Cosmos DB \u2013 for the first and second approach we are going to select \u201cCore (SQL)\u201d as our option as follows:<\/li>\n<\/ol>\n

        \"\"<\/p>\n

        You might need to create a new resource group and select an account name \u2013 for this demo I have named my account studentsdb.<\/p>\n

        Make sure your account name is all lowercase.<\/p>\n

        After that\u2019s done, click \u201cReview + create\u201d button to create your new Cosmos DB instance.<\/p>\n

        The creation process of a Cosmos DB instance might take between 1 \u2013 5 minutes depending on what type of configuration you\u2019ve chosen to build your instance.<\/p>\n

          \n
        1. When the creation is completed \u2013 go to the quick start option on the left side menu, you will be presented with the following options to work with Cosmos DB.\"\"<\/li>\n
        2. Select \u201c.NET Core\u201d option then click the \u201cCreate \u2018Items\u2019 Contains\u201d button \u2013 it will create a sample container for you to work with.<\/li>\n
        3. Once the items container is created, click the \u201cDownload\u201d button to download a full ASP.NET Core MVC solution for full CRUD operations to interact with the sample container you just created.\n\"\"<\/li>\n
        4. Now that you have downloaded the solution, build the solution, then try to run the solution to make sure all the configurations are set correctly, all dependencies are downloaded and that you can actually interact with the container in your Cosmos DB instance – in this demo I’m going to add a couple of records in the ToDoList.\n<\/span>(Note: you might be prompted by Visual Studio 2019 that you’re opening a solution downloaded from the internet – since Azure portal is a trusted source go ahead and click OK)<\/li>\n<\/ol>\n

          \"\"<\/p>\n

          To verify that the records you’ve created have been successfully persisted, you can go back to your Azure portal and click “Open Data Explorer” button to check the records you created.<\/p>\n

          The following screenshots show you the data navigation and retrieval on the data explorer window in Azure:<\/p>\n

          \"\"<\/p>\n

          This completes and verifies the setup portion of this first approach.<\/p>\n

          Now, let’s go ahead an utilize the CRUD operations code to build a new API and integrate OData.<\/p>\n

          You will notice that the solution we downloaded from Azure Portal implements the Repository pattern, which offer all CRUD operations needed to run an API.<\/p>\n

          For this demo, we will focus on the following code in ItemController.cs<\/em> file:<\/p>\n

                  private readonly IDocumentDBRepository<todo.Models.Item> Respository;\r\n        public ItemController(IDocumentDBRepository<todo.Models.Item> Respository)\r\n        {\r\n            this.Respository = Respository;\r\n        }\r\n\r\n        [ActionName(\"Index\")]\r\n        public async Task<IActionResult> Index()\r\n        {\r\n            var items = await Respository.GetItemsAsync(d => !d.Completed);\r\n            return View(items);\r\n        }<\/pre>\n
          We will create an API controller let’s call it ItemsController.cs\u00a0<\/em>and use the exact same code snippet above to build an endpoint that returns all items from Cosmos DB in JSON format – our new controller would look something like this:<\/p>\n
          using System.Collections.Generic;\r\nusing System.Threading.Tasks;\r\nusing Microsoft.AspNetCore.Mvc;\r\nusing todo;\r\nusing todo.Models;\r\n\r\nnamespace quickstartcore.Controllers\r\n{\r\n    [Produces(\"application\/json\")]\r\n    [Route(\"api\/Items\")]\r\n    public class ItemsController : Controller\r\n    {\r\n        private readonly IDocumentDBRepository<Item> Respository;\r\n        public ItemsController(IDocumentDBRepository<Item> Respository)\r\n        {\r\n            this.Respository = Respository;\r\n        }\r\n\r\n        \/\/ GET: api\/Items\r\n        [HttpGet]\r\n        public async Task<IEnumerable<Item>> Get()\r\n        {\r\n            return await Respository.GetItemsAsync(d => !d.Completed);\r\n        }\r\n    }\r\n}\r\n<\/pre>\n
          Let’s verify our endpoint is functional by hitting the endpoint in the browser or using a tool like Postman, your response for hitting an endpoint:<\/p>\n
          http:\/\/localhost:1234\/api\/items<\/pre>\n
          Your response should look something like this:<\/p>\n
          [\r\n    {\r\n        \"id\": \"3f0beb77-dd24-4b51-a921-6a34c60e7b4b\",\r\n        \"name\": \"Brush your teeth\",\r\n        \"description\": \"brush your teeth tonight\",\r\n        \"isComplete\": false\r\n    },\r\n    {\r\n        \"id\": \"739c3cef-58b6-48a6-ad8f-21b485bb326f\",\r\n        \"name\": \"Organize Office\",\r\n        \"description\": \"Organize your office\",\r\n        \"isComplete\": false\r\n    }\r\n]<\/pre>\n
           <\/p>\n
          OData Integration<\/h3>\n
          Now that we have implemented and verified our controller endpoint is functional, let’s do the exact same steps we’ve done in this article<\/a> to implement OData in our solution.\nI will summarize these steps here as follows:<\/p>\n
            \n
          1. Add a Nuget package Microsoft.AspNetCore.OData\u00a0<\/strong>to your solution.<\/li>\n
          2. Add OData service in your startup.cs<\/em> file, then enable dependency injection along with the functions you want OData to provide through your API, here’s an example of how your file should look:\n
            using System.Linq;\r\nusing Microsoft.AspNet.OData.Extensions;\r\nusing Microsoft.AspNetCore.Builder;\r\nusing Microsoft.AspNetCore.Hosting;\r\nusing Microsoft.Extensions.Configuration;\r\nusing Microsoft.Extensions.DependencyInjection;\r\nusing Microsoft.Extensions.Logging;\r\nusing todo;\r\n\r\nnamespace quickstartcore\r\n{\r\n    public class Startup\r\n    {\r\n        public Startup(IHostingEnvironment env)\r\n        {\r\n            var builder = new ConfigurationBuilder()\r\n                .SetBasePath(env.ContentRootPath)\r\n                .AddJsonFile(\"appsettings.json\", optional: true, reloadOnChange: true)\r\n                .AddJsonFile($\"appsettings.{env.EnvironmentName}.json\", optional: true)\r\n                .AddEnvironmentVariables();\r\n            Configuration = builder.Build();\r\n        }\r\n\r\n        public IConfigurationRoot Configuration { get; }\r\n        public void ConfigureServices(IServiceCollection services)\r\n        {\r\n            \/\/ Add framework services.\r\n            services.AddMvc();\r\n\r\n            services.AddSingleton<IDocumentDBRepository<todo.Models.Item>>(new DocumentDBRepository<todo.Models.Item>());\r\n            services.AddOData();\r\n        }\r\n\r\n        public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)\r\n        {\r\n            loggerFactory.AddConsole(Configuration.GetSection(\"Logging\"));\r\n            loggerFactory.AddDebug();\r\n\r\n            if (env.IsDevelopment())\r\n            {\r\n                app.UseDeveloperExceptionPage();\r\n                app.UseBrowserLink();\r\n            }\r\n            else\r\n            {\r\n                app.UseExceptionHandler(\"\/Home\/Error\");\r\n            }\r\n\r\n            app.UseStaticFiles();\r\n\r\n            app.UseMvc(routes =>\r\n            {\r\n                routes.MapRoute(\r\n                    name: \"default\",\r\n                    template: \"{controller=Item}\/{action=Index}\/{id?}\");\r\n\r\n                routes.EnableDependencyInjection();\r\n                routes.Select().Filter().OrderBy().Expand();\r\n            });\r\n        }\r\n    }\r\n}<\/pre>\n<\/li>\n
          3. Let’s update our controller (ItemsController.cs<\/em>) to enable OData query – your controller file should look as follows:\n
            using System.Collections.Generic;\r\nusing System.Threading.Tasks;\r\nusing Microsoft.AspNet.OData;\r\nusing Microsoft.AspNetCore.Mvc;\r\nusing todo;\r\nusing todo.Models;\r\n\r\nnamespace quickstartcore.Controllers\r\n{\r\n    [Produces(\"application\/json\")]\r\n    [Route(\"api\/Items\")]\r\n    public class ItemsController : Controller\r\n    {\r\n        private readonly IDocumentDBRepository<Item> Respository;\r\n        public ItemsController(IDocumentDBRepository<Item> Respository)\r\n        {\r\n            this.Respository = Respository;\r\n        }\r\n\r\n        \/\/ GET: api\/Items\r\n        [HttpGet]\r\n        [EnableQuery()]\r\n        public async Task<IEnumerable<Item>> Get()\r\n        {\r\n            return await Respository.GetItemsAsync(d => !d.Completed);\r\n        }\r\n    }\r\n}\r\n<\/pre>\n<\/li>\n
          4. Let’s verify our new endpoint with OData integration by hitting an endpoint like:\n
            http:\/\/localhost:36442\/api\/items?$select=name<\/pre>\n
            And your response should look as follows:<\/p>\n
            [\r\n    {\r\n        \"name\": \"Brush your teeth\"\r\n    },\r\n    {\r\n        \"name\": \"Organize Office\"\r\n    }\r\n]<\/pre>\n
             <\/li>\n<\/ol>\n
            By seeing this result, we verified OData is functional on your API retrieving and processing data from your Cosmos DB instance container.\nIn the next article, we will discuss working with OData & Cosmos DB using the EntityFramework in ASP.NET Core API.<\/p>\n
            Final Notes<\/h3>\n
              \n
            1. You can download the solution I used to run this demo from here<\/a> (Don’t forget to update the endpoint & key values in DocumentDBRepository.cs<\/em> file.<\/li>\n
            2. The current demo uses ASP.NET Core 2.2 example, but there are so many other options including classic ASP.NET MVC applications that I encourage you to try out.<\/li>\n
            3. The current demo uses Item as a model, you will need to modify the solution slightly to work with whatever model you want to run your application.<\/li>\n
            4. I highly recommend following this link<\/a> to learn more about Cosmos DB and it’s capabilities.<\/li>\n
            5. Huge thanks to Cosmos DB team for providing such a great documentation around such powerful technology.<\/li>\n
            6. I also highly recommend staying up-to-date with all the new updates in Cosmos DB by following this link<\/a> to their blog.<\/li>\n<\/ol>\n
               <\/p>\n","protected":false},"excerpt":{"rendered":"
              We talked in previous articles about the pluggability of OData with any storage technology regardless of its schema, whether it\u2019s a SQL-based storage, NoSQL, In-Memory or simply a file on a hard-drive. This power of OData enables developers to work with powerful, planet-scale storage technologies such as Cosmos DB. In this article we are going […]<\/p>\n","protected":false},"author":3348,"featured_media":3345,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1,117],"tags":[],"class_list":["post-3335","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-odata","category-webapi"],"acf":[],"blog_post_summary":"
              We talked in previous articles about the pluggability of OData with any storage technology regardless of its schema, whether it\u2019s a SQL-based storage, NoSQL, In-Memory or simply a file on a hard-drive. This power of OData enables developers to work with powerful, planet-scale storage technologies such as Cosmos DB. In this article we are going […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/3335","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/users\/3348"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/comments?post=3335"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/3335\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/media\/3345"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/media?parent=3335"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/categories?post=3335"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/tags?post=3335"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}