Edit on GitHub
Report issue
Page history

Using Cloud Spanner in ASP.NET

Author(s): @benwulfe ,   Published: 2017-11-03

This tutorial describes how to use the C# Google Cloud Spanner ADO.NET library to build a simple REST API for books and use the API to store and query books.

Cloud Spanner is a hosted SQL database, and the Cloud Spanner ADO.NET provider lets you take advantage of Cloud Spanner in your C# applications. The Cloud Spanner ADO.NET library is fully asynchronous to the network level and is the recommended way to integrate Cloud Spanner APIs into your .NET applications.

What you’ll use in this tutorial:


Cloud Spanner charges based on the number of nodes, storage and bandwidth used. See Cloud Spanner detailed pricing for more information.

Before you begin

  1. Set up the following on your development machine:

    1. Set up the Cloud SDK.
    2. Set up authentication and authorization for the Cloud SDK. This tutorial uses the Google Default Application Credentials when calling Google APIs to access your data.
    3. Install Microsoft Visual Studio 2017. The community edition is free.
  2. Go to the Spanner page in the Cloud Platform Console and create or select a project to use for this tutorial.

Creating a Cloud Spanner database

  1. Go to the Spanner page in the Cloud Platform Console.
  2. Create a new Cloud Spanner instance named myspanner.
  3. Create a new database named books.
  4. Add a table named bookTable.
  5. Define the schema for bookTable as shown and set the primary key to ID.

image alt text

Creating an ASP.NET Core Web API application

This REST API provides basic create, read, update, and delete (CRUD) operations on books in the bookTable database.

Note: You can download a completed version of the application here.

  1. To create the application:

    1. From the menu, click File > New Project > C# > Web > ASP.NET Core Web Application (.NET Core).
    2. Choose Web API.

    image alt text

    1. For the project name, enter SpannerTest.
  2. Using the Manage Nuget Packages dialog, add a reference to the Cloud Spanner nuget.

    image alt text

  3. To create a Model class for a book:

    1. Add a new folder named Models in the project.
    2. In the Models folder, add a class named Book with the following content:

      namespace SpannerTest.Models
          public class Book
              public string Id { get; set; }
              public string Author { get; set; }
              public string Title { get; set; }
              public DateTime PublishDate { get; set; }
  4. To create a Controller class to handle the HTTP requests:

    1. In the Controllers folder, add a new Web API Controller class item named BooksController.
    2. Delete the contents of the controller.
    3. To list all books, add a GetAll method to BooksController and replace myProject with your project ID.

      See the example GetAll method.

    4. To get a single book, add a Get method to BooksController and replace myProject with your project ID.

      See the example Get method.

    5. To insert records, add a Create method to BooksController and replace myProject with your project ID.

      See the example Create method.

Adding books and testing the application

To run the application, use a utility to send REST requests to test the API. This example shows Postman, a Chrome extension, but you can use curl or another utility.

  1. To add a book to the database, perform an HTTP POST with the port that your local server is running on. For example, replace port 56777 in http://localhost:56777.
  2. To test the application, perform an HTTP GET:

    • To return all books, enter: http://localhost:PORT_NUMBER/api/books
    • To return a single book, enter: http://localhost:PORT_NUMBER/api/books/ID

image alt text

[Optional] Deploy to Google App Engine Flex

For automatic scaling and management, you can deploy your Web API project to the App Engine flexible environment.

  1. Download and install Google Cloud Tools for Visual Studio.
  2. In the main menu, select Tools > Google Cloud > Publish to Google Cloud.
  3. In the Publish dialog box, choose App Engine Flex.

    image alt text

  4. Click Publish. After publishing completes, the application is live at [https://YOUR_PROJECT_ID.appspot.com](https://YOUR_PROJECT_ID.appspot.com).

Cleaning Up

Once you are done, you should delete your database to avoid unnecessary charges.

  1. Navigate to the Spanner page.
  2. Select the instance you created.
  3. Choose Delete Instance.

What's next

This basic tutorial does not have everything in a typical ASP.NET application. For enterprise-grade software you'll need to consider transactions, transient faults, and exponential backoff. The Cloud Spanner library for ADO.NET supports handling these issues, and you can read more about this in Getting Started with Cloud Spanner in C#.

If you find a bug please log it on the issue tracker.

Submit a Tutorial

Share step-by-step guides


Request a Tutorial

Ask for community help


GCP Tutorials

Tutorials published by GCP


Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.