Skip to main content

Posts tagged with 'csharp'

Swashbuckle is a handy library to easily bring Swagger support to your ASP.NET Core (or ASP.NET) application. It is especially handy when developing an HTTP based API. It creates a form of interactive documentation based on the OpenAPI Specification.

Before diving into Swashbuckle: Merry Christmas! This blog is being posted on December 25th, 2017. It’s the final post of the very first C# Advent Calendar. Please check out the other 24 posts in the series! This event has gone so well, that I’m already planning on doing it again in 2018. Thank you, again, to everyone who participated (whether you are a writer or you’ve just been following along).

The full source code used in this example is available on Github.

ASP.NET Core HTTP API

I’m going to assume some level of familiarity with ASP.NET Core and creating a REST API. Here’s an example of a GET and a POST. These endpoints are reading/writing from a JSON text file (in a way that is probably not thread-safe and definitely not efficient, but it’s fine for this example).

public class ValuesController : Controller
{
    [HttpGet]
    [Route("api/teams")]
    public IActionResult GetTeams()
    {
        var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
        var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
        return Ok(teams);
    }

    [HttpPost]
    [Route("api/team")]
    public IActionResult PostTeam([FromBody]Team team)
    {
        var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
        var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
        teams.Add(team);
        System.IO.File.WriteAllText("jsonFile.json",JsonConvert.SerializeObject(teams));
        return Ok(team);
    }

    // etc...

To try out the GET endpoint, the simplest thing I can do is open a browser and view the results. But to try out the POST endpoint, I need something else. I could install Postman or Fiddler (and you should). Here’s how that would look.

Postman

Postman is great for interacting with endpoints, but Postman alone doesn’t really tell us anything about the endpoint or the system as a whole. This is where Swagger comes in.

Swagger

Swagger is a standard way to provide specifications for endpoints. Usually, that specification is automatically generated and then used to generate an interactive UI.

We could write the Swagger spec out by hand, but fortunately ASP.NET Core provides enough information to generate a spec for us. Look at the PostTeam action above. Just from reading that we know:

  • It expects a POST

  • The URL for it is /api/team

  • There’s a Team class that we can look at to see what kind of body is expected

From that, we could construct a Swagger spec like the following (I used JSON, you can also use YAML).

{
	"swagger": "2.0",
	"info": { "version": "v1", "title": "Sports API" },
	"basePath": "/",
	"paths": {
		"/api/team": {
			"post": {
				"consumes": ["application/json"],
				"parameters": [{
					"name": "team",
					"in": "body",
					"required": false,
					"schema": { "$ref": "#/definitions/Team" }
				}]
			}
		}
	},
	"definitions": {
		"Team": {
			"type": "object",
			"properties": {
				"name": { "type": "string" },
				"stadiumName": { "type": "string" },
				"sport": { "type": "string" }
			}
		}
	}
}

But why on earth would you want to type that out? Let’s bring in a .NET library to do the job. Install Swashbuckle.AspNetCore with NuGet (there’s a different package if you want to do this with ASP.NET).

You’ll need to add a few things to Startup.cs:

In the ConfigureServices method:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Sports API", Version = "v1"});
});

In the Configure method:

app.UseSwagger();

Aside: With ASP.NET, NuGet actually does all this setup work for you.

Once you’ve done this, you can open a URL like http://localhost:9119/swagger/v1/swagger.json and see the generated JSON spec.

Swagger spec in JSON

Swagger UI with Swashbuckle

That spec is nice, but it would be even nicer if we could use the spec to generate a UI.

Back in the Configure method, add this:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Sports API v1");
});

Now, open your site and go to /swagger:

Swagger UI generated by Swashbuckle

Some cool things to notice:

  • Expand/collapse by clicking the URL of an endpoint (note that you must use Route attributes for Swashbuckle to work with ASP.NET Core).

  • "Try it out!" buttons. You can execute GET/POST right from the browser

  • The "parameter" of the POST method. Not only can you paste in some content, but you get an example value that acts like a template (just click it).

Giving some swagger to your Swagger

Swagger and Swashbuckle have done a lot with just a little bit. It can do even more if we add a little more information in the code.

  • Response: The ProducesResponseType attribute will let Swagger know what the response will look like (this is especially useful if you are using IActionResult and/or an endpoint could return different types in different situations).

  • Comments: If you are using XML comments, you can have these included with the Swagger output.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Sports API", Version = "v1" });
    var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "swashbuckle-example.xml");
    c.IncludeXmlComments(filePath);
});

(Also make sure you XML Documentation output for your project enabled)

Here’s an example of a GetTeams method with both XML comments and ProducesResponseType:

/// <summary>
/// Gets all the teams stored in the file
/// </summary>
/// <remarks>Baseball is the best sport</remarks>
/// <response code="200">List returned succesfully</response>
/// <response code="500">Something went wrong</response>
[HttpGet]
[Route("api/teams2")]
[ProducesResponseType(typeof(Team), 200)]
public IActionResult GetTeams2()
{
    var jsonFile = System.IO.File.ReadAllText("jsonFile.json");
    var teams = JsonConvert.DeserializeObject<List<Team>>(jsonFile);
    return Ok(teams);
}
  • Customize your info: there’s more to the Info class than just Title and Version. You can specify a license, contact, etc.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Title = "Sports API",
        Version = "v1",
        Description = "An API to list and add sports teams",
        TermsOfService = "This is just an example, not for production!",
        Contact = new Contact
        {
            Name = "Matthew Groves",
            Url = "https://crosscuttingconcerns.com"
        },
        License = new License
        {
            Name = "Apache 2.0",
            Url = "http://www.apache.org/licenses/LICENSE-2.0.html"
        }
    });
    var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "swashbuckle-example.xml");
    c.IncludeXmlComments(filePath);
});

Here’s a screenshot of the UI that has all three of the above enhancements: response type, XML comments, and more customized info.

Swagger with more swagger

Summary

Working on HTTP-based APIs? Bring Swashbuckle and Swagger into your life!

More resources:

Thanks again for reading the 2017 C# Advent!

This is a repost that originally appeared on the Couchbase Blog: ASP.NET Core with Couchbase: Getting Started.

ASP.NET Core is the newest development platform for Microsoft developers. If you are looking for information about plain old ASP.NET, check out ASP.NET with Couchbase: Getting Started.

ASP.NET Core Tools to Get Started

The following video will take you from having no code to having an HTTP REST API that uses Couchbase Server, built with ASP.NET Core.

These tools are used in the video:

Getting Started Video

In the video, I touch quickly on Scan Consistency. For more details on that, check out the Scan Consistency documentation or read a blog post that I wrote introducing AtPlus, which also covers the other types of Scan Consistency.

Summary

This video gives you the absolute minimum to get started with Couchbase by walking you through a simple CRUD application.

If you have any questions, please leave a comment. Or, you can always ask me questions on Twitter @mgroves.

UPDATE: The calendar is full. You can sign up to be an alternate, in case someone drops out or fails to deliver. I can't give you a date though, so you'd essentially have to have a post ready to go as soon as December 1st. And please, don't let the lack of an advent date keep you from writing that C# blog post! Finally, due to the tremendous response, I will double up the slots next year (from 25 to 50), assuming this advent goes well :)

I heard about the F# Advent Calendar, a traditional that's been carried on since 2010 (2014 in English). I think this is a great idea, and there needs to be one for C# too!

(I asked Sergey Tihon for permission!)

So, I need you to write a C# blog post!

Here are the rules:

  1. Reserve a slot on Twitter (with hash tag #csadvent) or leave a comment on this post. You do not have to announce your topic until the day you reserve.
  2. Prepare a blog post (in English).
  3. Add a link in your blog post that links back to here, so that your readers may find the entire advent.
  4. Publish your blog post on the specified date. Your post must be related to C# in some way, but otherwise the content is completely up to you. I've posted a few ideas below to get your creativity flowing.
  5. Post the link to your post on Twitter with hashtags #csharp and #csadvent

Below are all the slots, and who has claimed each date. I chose to go with 25 total slots (yes I know some advent calendars are 24).

I will do my best to keep this up to date. The slots will be first come first serve. I have already claimed December 25th for myself, since I assume that will be the least desirable date. But I'm happy to swap if you really really want that day.

DateClaimed byBlog Post
Dec 1, 2017 Hilary Weaver-Robb Combining Integration and UI Automation in C#
Dec 2, 2017 Jamie Rees Open Source, 2 years retrospective
Dec 3, 2017 Lucas Lansky Analyzing unit-ness of white-box tests using OpenCover
Dec 4, 2017 Andrei Ignat AOP with Roslyn–part 3–custom code at beginning of each method
Dec 5, 2017 Baskar rao Dsn Quick Actions in Visual Studio 2017
Dec 6, 2017 Bill Sempf Coding for an encrypted service
Dec 7, 2017 Brant Burnett Who says C# interfaces can't have implementations?
Dec 8, 2017 Lee Englestone Creating Alexa Skills with Web-API and hosting on Microsoft Azure
Dec 9, 2017 James Hickey Deck the Halls With Strategy Pattern Implementations in C#: Basic to Advanced
Dec 10, 2017 Carl Layton Using C# dynamic Keyword To Replace Data Transfer Objects
Dec 11, 2017 James Curran An Exercise in Refactoring - Specification Pattern
Dec 12, 2017 Andrew Lock Creating a .NET Standard Roslyn Analyzer in Visual Studio 2017
Dec 13, 2017 Jonathan Danylko 5 More C# Extension Methods for the Stocking! (plus a bonus method for enums)
Dec 14, 2017 Gérald Barré (aka Meziantou) Interpolated strings: advanced usages
Dec 15, 2017 Baskar rao Dsn Using BenchMarkDotNet for Performance BenchMarking
Dec 16, 2017 Chris Bohatka Breaking Down Dependency Injection and Inversion of Control in C# with SimpleInjector
Dec 17, 2017 David Pine C# Special Edition
Dec 18, 2017 Barret Blake Using C# and Azure Cognitive Services Text Analytics to Identify and Relate Text Documents
Dec 19, 2017 Ed Charbeneau 5 .NET Standard Features You Shouldn’t Miss
Dec 20, 2017 Kevin Miller Things you Should do with Strings While You’re Coworkers are on Holiday and No One is Checking the Production Code Branch
Dec 21, 2017 Angus Kinsey What makes C# great?
Dec 22, 2017 Jim Wilcox Unloading the UI Thread in C# on Windows 10 + UWP
Dec 23, 2017 Duane Newman All I want for Christmas is a C# Build System
Dec 24, 2017 Calvin Allen Live Unit Testing in Visual Studio 2017
Dec 25, 2017 Matthew D. Groves Swashbuckle and Swagger with ASP.NET Core

Alternates:

  • Leave a comment or tweet with #csadvent to be put on this list!

Some ideas:

  1. Introduction to [your favorite NuGet package]
  2. X C# Tricks and Tips
  3. JSON (De)serialization
  4. Streams
  5. The newer C# 6 and 7 features
  6. Async/await

Thanks to everyone who is participating! I hope this goes well and it can become an annual tradition.

This is a repost that originally appeared on the Couchbase Blog: Azure Functions and Lazy Initialization with Couchbase Server.

Azure Functions are still new to me, and I’m learning as I’m going. I blogged about my foray into Azure Functions with Couchbase over a month ago. Right after I posted that, I got some helpful feedback about the way I was instantiating a Couchbase cluster (and bucket).

I had (wrongly) assumed that there was no way to save state between Azure Function calls. This is why I created a GetCluster() method that was called each time the function ran. But, initializing a Couchbase Cluster object is an expensive operation. The less often you instantiate it, the better.

You can follow along with the updated source code for this blog post on Github.

Static state

I had a hard time finding documentation on whether I could use a static object for reuse between function calls. I suppose I should have experimented, like fellow Microsoft MVP Mark Heath did. Instead, I posed the question to StackOverflow.

In short: yes. A Cluster, instantiated and saved to a static member, can is reusable between function calls. According to Mark’s post above, there’s no guarantee how long this value will survive. But that’s an expected trade-off that you make when going "serverless".

Lazy initializing within Azure Functions

Simply using a static member would work, but it’s not thread-safe. There are a few ways to tackle that issue, but an easy way that’s built right into the .NET framework is to use Lazy Initialization with Lazy<T>.

Lazy Initialization in Azure Functions

First, I removed the GetBucket and GetCluster methods. Next, I created a Lazy<IBucket> property to replace them.

private static readonly Lazy<IBucket> Bucket = new Lazy<IBucket>(() =>
{
    var uri = ConfigurationManager.AppSettings["couchbaseUri"];
    var bucketName = ConfigurationManager.AppSettings["couchbaseBucketName"];
    var bucketPassword = ConfigurationManager.AppSettings["couchbaseBucketPassword"];
    var cluster = new Cluster(new ClientConfiguration
    {
        Servers = new List<Uri> { new Uri(uri) }
    });
    return cluster.OpenBucket(bucketName, bucketPassword);
});

I just made a single property for a bucket, since that’s all I need for this example. But if you need to use the cluster, you can easily make that its own Lazy property. (Once you have a cluster, getting a bucket is a relatively cheap operation).

Using a Lazy property

When you instantiate a Lazy<T> object, you supply it with an initialization lambda. That lambda won’t execute until the Value property is actually called for the first time.

var lazyObject = new Lazy<string>(() =>
{
    // this code won't be called until 'lazyObject.Value' is referenced
    // for the first time
    return "I'm lazy!";
});

For instance, notice the Value between Bucket and GetAsync in the updated version of my Azure Functions:

var doc = await Bucket.Value.GetAsync<MyDocument>(id);

If that’s the first time Value is used, the cluster will be initialized. Otherwise, it will use the already initialized cluster (try experimenting with a Guid instead of a Bucket).

Summary

State can be saved between Azure Function calls by using a static member. Make sure that it’s thread-safe (by using Lazy<T> or something like it). Don’t make any assumptions about how long that object will be around.

Anything else I missed? Are you using Azure Functions with Couchbase? I would love to hear from you. Please leave a comment below or ping me on Twitter @mgroves.

This is a repost that originally appeared on the Couchbase Blog: Azure Functions with Couchbase Server.

Azure Functions are Microsoft’s answer to Amazon’s Lambdas or Google’s Cloud Functions (aka "serverless" architecture). They give you a way to deploy small pieces of code, and let Azure handle the underlying server. I’ve never used them before, so I thought I would give them a try beyond "Hello, World", by getting them to work with Couchbase Server.

There are more options in Azure Functions beyond simple HTTP events (e.g. Blob triggers, GitHub webhooks, Azure Storage queue triggers, etc). But, for this blog post, I’m going to focus on just HTTP events. I’ll create simple "Get" and "Set" endpoints that interact with Couchbase Server.

Before beginning, you can follow along by getting the source code for this blog post on GitHub.

Also, please read the Azure Functions and Lazy Initialization with Couchbase Server post. It contains an important update about using Couchbase Server and Azure Functions.

Getting setup to develop Azure Functions

For this blog post, I decided to try Visual Studio Preview.

Visual Studio Preview

I did this because there is a handy tool for creating Azure Function projects in Visual Studio.

Azure Functions tool for Visual Studio

But it only works for the preview version at this time. You don’t have to use these tools to develop Azure Functions, but it made the process simpler for me.

Once I had this tooling in place, all I had to was to File→New→Project. Then under "Cloud", select "Azure Functions".

New Azure Functions in Visual Studio

Once you do this, you’ll have an empty looking project with a couple of JSON files. Right click on the project, add item, and select "Azure Function".

Add Azure Function

Next, you’ll need to select what kind of Azure Function you want to create. I chose "HttpTrigger". I also chose "Anonymous" to keep this post simple, but depending on your use case, you may want to require an authentication token. After you do this, a very simple shell of a function will be generated (as a C# class). You can execute this function locally (indeed, that is what the local.settings.json file is for) so you can test it out without deploying to Azure yet.

Writing a "Get" function

First, I decided that I wanted two Azure Functions: one to "get" a piece of data by ID, and one to "set" a new piece of given data. I started by defining the shape of my data with a simple C# POCO:

public class MyDocument
{
    public string Name { get; set; }
    public int ShoeSize { get; set; }
    public decimal Balance { get; set; }
}

Here is the Azure function that I wrote to "get" that document from Couchbase Server:

public static async Task<HttpResponseMessage> Get([HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)]HttpRequestMessage req, TraceWriter log)
{
    // parse query parameter
    var id = req.GetQueryNameValuePairs()
        .FirstOrDefault(q => string.Compare(q.Key, "id", true) == 0)
        .Value;

    using (var cluster = GetCluster())
    {
        using (var bucket = GetBucket(cluster))
        {
            var doc = await bucket.GetAsync<MyDocument>(id);
            return req.CreateResponse(HttpStatusCode.OK, doc.Value, new JsonMediaTypeFormatter());
        }
    }
}

Some things to note:

  • I remove the "post" that was generated by the tooling, since I want this to only be a "get" function.

  • Parsing the query parameter seems like a lot of extra code for this simple case. You can alternatively create a "function with parameters"

  • GetCluster and GetBucket will be discussed later in this post. But the short story is that I want this code to work both locally and deployed to Azure

Next, run this function locally, and you’ll get a console screen that looks similar to this:

Azure Functions running locally

At the bottom, you’ll notice that it tells you the Azure Function URL(s). Assuming I had a document in Couchbase (I don’t yet), I could create an HTTP request with a tool like Postman to: http://localhost:7071/api/HttpTriggerCsharpGet?id=123456

Currently, if I do that, I’ll get "null" as a response (since I don’t have any validation or error checking code). So let’s move on and create a "Set" function.

Writing a "Set" function

The "Set" function will be slightly different. I want document information POSTed to it, and I want it to return a message like "New document inserted with ID 123456".

public static async Task<HttpResponseMessage> Set([HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = null)] MyDocument req, TraceWriter log)
{

    var id = Guid.NewGuid().ToString();

    using (var cluster = GetCluster())
    {
        using (var bucket = GetBucket(cluster))
        {
            await bucket.InsertAsync(id, req);
        }
    }

    return new HttpResponseMessage
    {
        Content = new StringContent($"New document inserted with ID {id}"),
        StatusCode = HttpStatusCode.OK
    };
}

This function has a similar shape to the Get, but some important things to note:

  • There is only "post" in the HttpTrigger attribute.

  • Instead of HttpRequestMessage as the first parameter, I’ve decided to use MyDocument, and let Azure Functions do the binding for me.

  • Since I don’t have HttpRequestMessage, I can’t call its CreateResponse method, so instead I instantiate a new HttpResponseMessage directly to return the success message at the end.

To create a request in Postman, I’ll use a URL of http://localhost:7071/api/HttpTriggerCsharpSet. In the headers, I’ll set Content-Type to "application/json". Finally, the body will be JSON:

{
    "Name": "matthew",
    "Balance": 107.18,
    "ShoeSize": 14
}

Now, when I POST that to the endpoint, I’ll get a response message of "New document inserted with ID f05ea97e-7c2f-4f88-b72d-19756f6a6f35".

Connecting to Couchbase Server

I have glossed over how these functions connect to Couchbase Server.

Previously, I mentioned two methods, GetCluster and GetBucket that will connect to the cluster and bucket, respectively.

private static Cluster GetCluster()
{
    var uri = ConfigurationManager.AppSettings["couchbaseUri"];
    return new Cluster(new ClientConfiguration
    {
        Servers = new List<Uri> { new Uri(uri) }
    });
}

private static IBucket GetBucket(Cluster cluster)
{
    var bucketName = ConfigurationManager.AppSettings["couchbaseBucketName"];
    var bucketPassword = ConfigurationManager.AppSettings["couchbaseBucketPassword"];

    return cluster.OpenBucket(bucketName, bucketPassword);
}

At this point, most of this code should be familiar if you’ve used Couchbase Server and the Couchbase .NET SDK before. I’m connecting to a single node cluster, and then connecting a bucket that has a password set (I’m using Couchbase Server 4.6).

But, the important thing to point out here is the use of Configuration.AppSettings. In the local.settings.json file, I’ve added these Couchbase settings to the Value section:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsDashboard": "",
    "couchbaseUri": "http://localhost:8091",
    "couchbaseBucketName": "azurefunctions",
    "couchbaseBucketPassword": "Password88!"
  }
}

When running Azure Functions locally, this file is used for configuration. I have Couchbase Server running locally with a bucket called "azurefunctions". Anything in "Values" can be accessed via Configuration.AppSettings.

Deploying to Azure

Before deploying the Azure Functions, I’ll need to create a Couchbase Cluster on Azure. This is very easy to do, thanks to Ben Lackey’s great work on the Azure Marketplace. Once that’s deployed, deploying the Azure Functions are also easy, thanks to Visual Studio.

Deploying Couchbase Server to Azure

Here is a short video walking you through the process of creating a Couchbase Server cluster on Azure.

For my example, I followed that video closely. Here is step 1, where I configure the username, password, and resource group.

Create Couchbase Cluster step 1

For the second step, I only created a single node cluster on the smallest, cheapest VM (DS1 v2). I created 0 Sync Gateway nodes, since I’m not using Sync Gateway for this example.

Create Couchbase Cluster step 1

Step 3 is just a summary, and step 4 is a confirmation. It will take 3-5 minutes for the Couchbase Cluster to start up in Azure.

Once the cluster is created, find the URL for the first node in the cluster (just as demonstrated in the above video). My URL looked something like: http://vm0.server-hsmkrefstzg2t.northcentralus.cloudapp.azure.com:8091. Go to this URL, login, and create a bucket (I called mine "azurefunctions", just like I did locally).

Deploying Azure Functions to Azure

Now, Couchbase Server is running. So let’s deploy the Azure Functions that will interact with it.

To begin, right-click the project in Visual Studio and select "publish". You’ll need to create a new publish profile the first time you do this, but that’s easy.

Publish Azure functions

Give your functions an app name, select a subscription, select a resource group (you can create a new one, or use the same group that you created above for Couchbase), select a service plan, and finally a storage account. You can create new ones when necessary.

Create Publish Profile

Click "create" and these items will start to be created in Azure (it may take a minute or two).

Trying out the Azure Functions

Finally, remember that the Azure Functions need to know the URI, bucket name, and password in order to connect to Couchbase Server. That information is in local.settings.json, but that file is not used for actual Azure deployments.

In the Azure portal, navigate to the Azure function (I called mine cbazurefunctions), and then select "Application Settings". Under "App settings", enter those three settings: couchbaseUri, couchbaseBucketName, and couchbaseBucketPassword.

Azure Functions App settings

Now, repeat the Postman process mentioned above to try out the Azure functions and make sure they work. Your URL will vary, but mine was http://cbazurefunctions.azurewebsites.net/.

Summary

This is my first time trying out Azure Functions. This blog post shows a simple demo, but there are other factors to consider before you start using this in production:

  • Authentication - I used anonymous Azure Functions to keep it simple. Azure Functions can also provide authentication tokens to use that prevent access except to authorized users.

  • App settings - Setting them manually in the portal may not be the best solution. There is probably a way to automate that portion, and that’s something I’ll look into in the future.

  • HTTPS/TLS - You will likely want to have some level of encryption as you are getting and posting data to your Azure Functions. The above example transmits everything in clear text.

Anything I missed? Any more tips or suggestions to share to make this process easier or better? Please leave a comment below or ping me on Twitter @mgroves.

Matthew D. Groves

About the Author

Matthew D. Groves lives in Central Ohio. He works remotely, loves to code, and is a Microsoft MVP.

Latest Comments

Twitter