Learn how you can use GraphQL in .NET Core and C#
Tags: beginners, dotnet, tutorial, webdev
Published: 2019-08-02 17:09:29

---
title: Learn how you can use GraphQL in .NET Core and C#
published: true
description: This shows how you can learn the foundations of GraphQL while using .Net and C#
tags: beginners, dotnet, tutorial, webdev 
cover_image: https://thepracticaldev.s3.amazonaws.com/i/i88zli770d8ns90u72c4.jpg
canonical_url: https://softchris.github.io/pages/dotnet-graphql.html
---


> GraphQL is this technology created by Facebook that enables the frontend to negotiate with the backend for what data it wants. It also enables the builder of the API to stitch together data from different APIs, should you wish it. It's a very cool piece of technology and it's not just for JavaScript, you can definitely use it for your next project in .Net.

In this article we will cover:

- WHY, why do we want this technology to build APIs from
- WHAT, what are the parts it consists of
- Demo, let's build an API and learn how we get that to work with our data sources

## Resources

- [GraphQL.org](https://graphql.org/)
This is the website for the GraphQL organization. It contains a lot of information on why GraphQL was built, what types exist and so on.

- [NuGet package graphql-dotnet](https://github.com/graphql-dotnet)
This is the most popular NuGet package there is. It contains a README page that helps you get started but also demos for different types of applications like MVC for example.

- [Starting with .Net Core in VS Code](https://code.visualstudio.com/docs/languages/dotnet?wt.mc_id=devto-blog-chnoring)
This shows how you can get started with .Net Core in VS Code.

- [Starter articles I wrote on .Net Core and VS Code](https://dev.to/softchris/net-core-series-learning-net-core-on-vs-code-and-how-you-can-create-a-serverless-api-3bm6)
I wrote a collection of articles for you that is curious about .Net Core. It shows how to build different types of projects, run tests and more. It even covers how to build a Serverless API.

- [How to build and consume GraphQL APIs in JavaScript](https://dev.to/azure/3-part-series-on-graphql-1fi1)
If you want to have a look at how things are done in JavaScript have a look at these articles I wrote.


## WHY, why do we need it in the first place. What's wrong with a REST API?

GraphQL allows for *content negotiation* which means you will only have one endpoint. It also allows you to query for exactly the fields you want. On the backend, you can grab the data from different data sources so there definitely is a good reason to be excited, for frontend developers as well as backend developers.


## WHAT, what parts does GraphQL exist of

GraphQL consists of a schema definition. You can define that schema in something called GQL, GraphQL Query Language but you can also decorate classes to respond to certain resource requests (more on that one in future articles).

Besides from the schema, there is a central concept called *resolvers*. A resolver is simply a function that knows what to do with an incoming query. A resolver is mapped to a certain resource.

Then you have a visual environment called GraphiQL that allows you to run queries. Some form of visual environment comes with most implementations of GraphQL.

### How to query

GraphQL looks a bit special when you query it but it's quite simple. To query a resource you would type so:

```
{ 
  resource
}
```

That's not enough, however. You also need to specify what columns you want, like so:

```
{
  resource {
    column,
    column2
  }
}
```

To query with a parameter you would instead type like so:

```
{
  users(id:1) {
    name,
    created
  }
}
```

The end result is always a JSON response that matches your query. So if we take the above query we would get something back looking like the following:

```json
{
  "data": {
    "users": [{
      "name" : "chris",
      "created": "2018-01-01"  
    }]
  }
}
```


## Demo - let's build an API. 

> We need to mix some GraphQL theory with code. So we will introduce a concept and then show code for it.

### Set up

We will need to do the following

1. **Create** a solution
2. **Create** a console app
3. **Install** the GraphQL NuGet package

**Create a solution**

Let's start by creating a solution directory like so:

```
mkdir demo
cd demo

```

Next, let's create the actual solution file:


```
dotnet new sln
```

**Create the Console app**

Creating a console project is as simple as typing:

```
dotnet new console -o App
```

Then navigate into it the project directory:

```
cd App
```

**Adding our GraphQL NuGet library**

Next, let's add our GraphQL NuGet package

```
dotnet add package GraphQL
```

### Hello GraphQL

Now we are ready to add code

```csharp
// Program.cs

using System;
using GraphQL;
using GraphQL.Types;

namespace App
{
  class Program
  {
    static void Main(string[] args)
    {
      Console.WriteLine("Hello World!");
      var schema = Schema.For(@"
          type Query {
              hello: String
          }
          ");

      var root = new { Hello = "Hello World!" };
      var json = schema.Execute(_ =>
      {
          _.Query = "{ hello }";
          _.Root = root;
      });

      Console.WriteLine(json);
    }
  }
}
```

There are three interesting parts in the above code:

1. **Declaring** our schema
2. **Defining** our resolver
3. **Executing our query** the API

**Declaring our schema**

The string that we feed into `Schema.For` contains something called GQL or GraphQL Query Language. It defines three things generally:

1. **Query**, this is what we can query for
2. **Types**, we don't have any types yet but we will later on in the article.
3. **Mutation**, this is what we can call that semantically means that we will change something

Let's especially focus on the parts where we set up our schema:

```csharp
var schema = Schema.For(@"
  type Query {
      hello: String
  }
");
```

For now, we only have the `type Query` and what it says is that we can query for `hello` and that the response is of type string, `hello: string`.

**Resolving our query**

A schema is just one part of the puzzle. The other part is the resolver code. This piece of code is what actually handles an incoming request. In our case the resolver code looks like this:

```csharp
var root = new { Hello = "Hello World!" };
```

As we can see above it maps something inside of our query `hello` and says that - if the user asks for `hello`, then we will answer with `Hello World`.

**Executing the query**

In the below code we execute our query `{ hello }` by assigning it to the property `_.Query` in the lambda expression we provide to `schema.Execute()`.

```csharp
var json = schema.Execute(_ =>
{
    _.Query = "{ hello }";
    _.Root = root;
});
```

Then the result of our query is assigned to our variable `json` and we can easily print that to the terminal using:

```csharp
Console.WriteLine(json); 
```

### Schema first

This is a different approach in which we will use classes and decorate them, the idea is that the classes will contain methods that will serve as resolvers when we make a query. 

To do it this way we need to do the following:

1. **Update** our schema, we need a new custom type and we need to expose it in the `Query`

2. **Create** some classes that we need to support our Type, our Query and also an in-memory database

**Schema update**

Our schema so far had no custom types. Let's change that by adding the type `Jedi` and let's also expose it as something we can query for, like so:

```csharp

Schema.For(@"
  type Jedi {
      name: String,
      side: String
  }

  type Query {
      hello: String,
      jedis: [Jedi]
  }
  ", _ =>
{
_.Types.Include<Query>();
});
```

Above we are adding `Jedi` as a type by writing `type Jedi` and also define its properties within `{}`. Then we add `jedis` to the `Query` and say it's of type `[Jedi]` which means it's an array of `Jedi`. Lastly, we give our `Schema.For()` a second argument:

```csharp
_.Types.Include<Query>();
```

This means we are pointing out a class `Query` that will handle all incoming requests. We don't have that class yet so let's create it.

**Creating supporting classes**

First, we need the class `Query`. It now has the responsibility to handle anything inside of `Query` in our schema, which means it needs to handle `hello` and `jedis`. Let's have a look at what `Query` can look like:

```csharp
public class Query 
{
    [GraphQLMetadata("jedis")]
    public IEnumerable<Jedi> GetJedis() 
    {
        return StarWarsDB.GetJedis();
    }

    [GraphQLMetadata("hello")]
    public string GetHello() 
    {
        return "Hello Query class";
    }
}
```

Here we are defining two methods `GetJedis()` and `GetHello()`. Note how we use the decorator `GraphQLMetadata` on each of the methods to *map* which property in our `Query` that they will handle. We see also that we make a call to a class `StarWarsDB` so we need to create that next:

```csharp
public static IEnumerable<Jedi> GetJedis() 
{
    return new List<Jedi>() {
        new Jedi(){ Name ="Luke", Side="Light"},
        new Jedi(){ Name ="Yoda", Side="Light"},
        new Jedi(){ Name ="Darth Vader", Side="Dark"}
    };
}
```

**Defining what to query for**

Let's define the query that we will use to Query our GraphQL API:

```gql
{ jedis { name, side } }
```

What we are saying above is that we want to query for `jedis` and we want the columns `name` and `side`. Compare this to a SQL expression where we would instead type:

```sql
SELECT name, side
FROM jedis;
```

Let's update the code with our query like so:

```csharp
var json = schema.Execute(_ =>
{
    _.Query = "{ jedis { name, side } }";
});

Console.WriteLine(json);
```

and the result is: 

![](https://thepracticaldev.s3.amazonaws.com/i/tubbgxeo8uh89bsu4leq.png)

That seems to work fine, alright :)

### Working with parameters

Now we got a lot working already but we need to be able to handle parameters, sometimes we just want one record back so we need to filter a bigger collection based on a key. To make this happen we need to:

1. **Update** our Schema to support a query with a parameter

2. **Create** a method in our Query class that is able to parse out the parameter

3. **Verify** that everything works

**Updating our schema**

First off, we need to update our schema so we support a query that takes a parameter, like so:

```csharp

Schema.For(@"
  type Jedi {
      name: String,
      side: String,
      id: ID
  }

  type Query {
      hello: String,
      jedis: [Jedi],
      jedi(id: ID): Jedi
  }
  ", _ =>
{
_.Types.Include<Query>();
});
```

We are actually doing two things above. We are adding the field `id` to the `Jedi` type. We are also adding this row to `Query`:

```gql
jedi(id: ID): Jedi
```

**Updating our code**
Our Jedi class didn't have an `Id` field so we need to add that, like so:

```csharp
public class Jedi 
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Side { get; set; }
}
```

Next, we need to add a method to our query class, like so:

```csharp
[GraphQLMetadata("jedi")]
public Jedi GetJedi(int id)
{
    return StarWarsDB.GetJedis().SingleOrDefault(j => j.Id == id);
}
```

Note above how we just need to name match `id` as an input parameter. The code itself is just a `SingleOrDefault` LINQ query that gives us one entry back.

**Updating the query**

Let's try to query for this new resource like so:

```gql
{ jedi(id: 1) { name } }
```

and the result:

![](https://thepracticaldev.s3.amazonaws.com/i/3w761iap4orapq1cmkm9.png)

Works !!! :)

## Summary

We have covered a lot of ground. We've introduced the GQL, GraphQL Query Language. Furthermore, we've learned how to define resources in our schema, custom types and how to resolve these. There is a lot more to learn about GraphQL but this article is already long enough. I hope this was an interesting first look at it. In the next part, we will cover how to build a Serverless API and leverage GraphQL that way and deploy it to the Cloud.