Functions binding Cosmos DB, C# -- 1

I was trying Cosmos DB binding for Azure Functions, and want to share what I learned. This is a basic skill for Azure users because it uses Cosmos DB that can handle Json files easily, and Azure Functions that manages http requests. Below is the system configuration.

Environment setup

Visual Studio 2017
  Azure Functions and Web Jobs Tools
  Microsoft.NET.Sdk.Functions
  Microsoft.Azure.WebJobs.Extensions.ComosDB

Cosmos DB

  Database Name: "VehicleSpec"
  Collection Name: "Vehicles"
  Connection String: <CosmosDBConnectionString>

The Cosmos DB has 10 documents below.

"id": "d7b70f4a-6cb0-e56d-2c41-1698a5a2bb0b"

``` { "id": "d7b70f4a-6cb0-e56d-2c41-1698a5a2bb0b", "maker": "Honda", "name": "Civic", "class": "LX", "type": "Hatchback", "engine": "NA", "transMission": "6MT", "horsePower": "158PS", "price": 19450 } ```

"id": "c4b2088f-85c1-c616-02c9-0f6f69e47a08"

``` { "id": "c4b2088f-85c1-c616-02c9-0f6f69e47a08", "maker": "Honda", "name": "Civic", "class": "Sport", "type": "Sedan", "engine": "NA", "transMission": "CVT", "horsePower": "158PS", "price": 21150 } ```

"id": "2ea20ecf-9087-3327-01ee-71a724954e3b"

``` { "id": "2ea20ecf-9087-3327-01ee-71a724954e3b", "maker": "Honda", "name": "Civic", "class": "EX", "type": "Sedan", "engine": "TurboCharged", "transMission": "CVT", "horsePower": "174PS", "price": 23400 } ```

"id": "1af97a2a-3a53-96ec-c470-dc13622f1dc0"

``` { "id": "1af97a2a-3a53-96ec-c470-dc13622f1dc0", "maker": "Honda", "name": "Accord", "class": "LX", "type": "Sedan", "engine": "TurboCharged", "transMission": "CVT", "horsePower": "192PS", "price": 23720 } ```

"id": "a273e3ad-058f-d456-2256-ff10baabcf5d"

``` { "id": "a273e3ad-058f-d456-2256-ff10baabcf5d", "maker": "Honda", "name": "Accord", "class": "Hybrid", "type": "Sedan", "engine": "TwoMotorHybrid", "transMission": "E-CVT", "horsePower": "181PS", "price": 25320 } ```

"id": "343d27e7-261f-3a6f-3981-35610f2c7671"

``` { "id": "343d27e7-261f-3a6f-3981-35610f2c7671", "maker": "Honda", "name": "Accord", "class": "EX", "type": "Sedan", "engine": "TurboCharged", "TransMission": "10AT", "HorsePower": "252PS", "price": 27620 } ```

"id": "f91cd57d-e45f-7cc7-8dcd-5f2d8099c47a"

``` { "id": "f91cd57d-e45f-7cc7-8dcd-5f2d8099c47a", "maker": "Nissan", "name": "Ultima", "class": "S", "type": "Sedan", "engine": "NA", "transMission": "7AT", "horsePower": "188PS", "price": 23750 } ```

"id": "d01aacba-2eeb-5c4a-6578-1852a2b4f0fe"

``` { "id": "d01aacba-2eeb-5c4a-6578-1852a2b4f0fe", "maker": "Toyota", "name": "Camry", "class": "L", "type": "Sedan", "engine": "NA", "transMission": "9AT", "horsePower": "203PS", "price": 23845 } ```

"id": "ef47cfc3-0639-cf06-904a-8db1ebf95cef"

``` { "id": "ef47cfc3-0639-cf06-904a-8db1ebf95cef", "maker": "Hyundai", "name": "Sonata", "class": "SE", "type": "Sedan", "engine": "NA", "transMission": "8AT", "horsePower": "185PS", "price": 22300 } ```

Sample Code
1. Read a single document, looking up "id" from query string
2. local.settings.json

3. Read a single document, looking up "id" from route data

4. Extract specific json properties

5. Read multiple documents

1. Read a single document, looking up "id" from query string

VehicleList.cs

``` using System; using Newtonsoft.Json; namespace FunctionsCosmosDB { public class VehicleList { [JsonProperty("id")] public Guid id { get; set; } [JsonProperty("maker")] public string Maker { get; set; } [JsonProperty("name")] public string Name { get; set; } [JsonProperty("class")] public string Class { get; set; } [JsonProperty("type")] public string Type { get; set; } [JsonProperty("engine")] public string Engine { get; set; } [JsonProperty("transMission")] public string TransMission { get; set; } [JsonProperty("horsePower")] public string HorsePower { get; set; } [JsonProperty("price")] public int Price { get; set; } } } ```

local.settings.json

``` { "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "UseDevelopmentStorage=true", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "CosmosDBConnection": <cosmosdbconnectionstring> } } ```

GetDocument.cs

``` using Microsoft.AspNetCore.Mvc; using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Extensions.Http; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; namespace FunctionsCosmosDB { public static class GetDocument { [FunctionName("GetDocument")] public static IActionResult Run( [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)] HttpRequest req, [CosmosDB(databaseName: "VehicleSpec", collectionName: "Vehicles", ConnectionStringSetting = "CosmosDBConnection", Id = "{Query.id}")] VehicleList vehicleList, ILogger log) { log.LogInformation("C# HTTP trigger function processed a request."); return vehicleList != null ? (ActionResult)new OkObjectResult(vehicleList) : new BadRequestObjectResult("Please pass a name on the query string or in the request body"); } } } ```

Sample request query and return

``` http://localhost:7071/api/GetDocument?id=f91cd57d-e45f-7cc7-8dcd-5f2d8099c47a ```

``` { "id": "f91cd57d-e45f-7cc7-8dcd-5f2d8099c47a", "maker": "Nissan", "name": "Ultima", "class": "S", "type": "Sedan", "engine": "NA", "transMission": "7AT", "horsePower": "188PS", "price": 23750 } ```

Point 1
Query string should be exact match

Point 2
When you set a wrong name of Cosmos DB database or collection, it returns "status": 400

Poitnt 3
For VehicleList class, type Guid is used, but string also works

2. local.settings.json
It is recommended that you develop Azure Functions locally using Visual Studio or Visual Studio Code. I do not find clarification in the official document, but you do not need to edit function.json by yourself, but it is automatically generated when you set up local.setting.json.
One thing I learned here is, if you do not want to describe the Cosmos DB setup parameters such as Database Name or Collection Name on Main method, you can pass it to local.settings.json. You can use Attribute property in between %, for example, databaseName: "%DatabaseName%" like below.
GetDocument.cs

``` using Microsoft.AspNetCore.Mvc; using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Extensions.Http; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; namespace FunctionsCosmosDB { public static class GetDocument { [FunctionName("GetDocument")] public static IActionResult Run( [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)] HttpRequest req, [CosmosDB(databaseName: "%DatabaseName%", collectionName: "%CollectionName%", ConnectionStringSetting = "CosmosDBConnection", Id = "{Query.id}")] VehicleList vehicleList, ILogger log) { log.LogInformation("C# HTTP trigger function processed a request."); return vehicleList != null ? (ActionResult)new OkObjectResult(vehicleList) : new BadRequestObjectResult("Please pass a name on the query string or in the request body"); } } } ```

local.settings.json

``` { "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "UseDevelopmentStorage=true", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "CosmosDBConnection": "<cosmosdbconnectionstring>", "DatabaseName": "VehicleSpec", "CollectionName": "Vehicles" } } ```

3. Read a single document, looking up "id" from route data

GetDocumentRoute.cs

``` using Microsoft.AspNetCore.Mvc; using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Extensions.Http; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; namespace FunctionsCosmosDB { public static class GetDocumentRoute { [FunctionName("GetDocumentRoute")] public static IActionResult Run( [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "vehicles/{id}")] HttpRequest req, [CosmosDB(databaseName: "VehicleSpec", collectionName: "Vehicles", ConnectionStringSetting = "CosmosDBConnection", Id = "{id}")] VehicleList vehicleList, ILogger log) { log.LogInformation("C# HTTP trigger function processed a request."); return vehicleList != null ? (ActionResult)new OkObjectResult(vehicleList) : new BadRequestObjectResult("Please pass a name on the query string or in the request body"); } } } ```

Sample request query and return

``` http://localhost:7071/api/vehicles/ef47cfc3-0639-cf06-904a-8db1ebf95cef ```

``` { "id": "ef47cfc3-0639-cf06-904a-8db1ebf95cef", "maker": "Hyundai", "name": "Sonata", "class": "SE", "type": "Sedan", "engine": "NA", "transMission": "8AT", "horsePower": "185PS", "price": 22300 } ```