ASP.NET Core with GraphQL using .NET Boxed

GraphQL is something I have been meaning to look into for a while, but haven’t found the time. Muhammad Rehan Saeed recent release of .NET Boxed, which is a rebranding of his ASP.NET Core Boilerplate templates, contains a template for GraphQL. This brought GraphQL back to the front of my mind so this post is going to walk through installing and using .NET Boxed to get a GraphQL project up and running.

Template Installation

As with all templates, installation is very easy using the .NET CLI. Open a command prompt and enter the following command.

dotnet new --install "Boxed.Templates::*"

The * at the end of the command is just making sure the latest version gets installed. After the installation is done you will get a list of all the template you have installed. The two new ones provided by .NET Boxed are highlighted in the screenshot.

Project Creation

For this post, we will be creating a project using the graphql template. Both of the templates provided by .NET Boxed have a lot of optional flags that can be used configure the resulting project. Make sure to run the help command for the template you are using to see if there are any option you want to set. For example, the following command would list all the options for the GraphQL template.

dotnet new graphql --help

Create and navigate to the directory you want the new project to be created in and then run the following command to create the project with the default setting with the exception of turning off HTTPS. Not something you want to turn off for a production application, but it reduces the complexity of the initial exploration.

dotnet new graphql --https-everywhere false

With the project created run the following command from the same directory to open it in Visual Studio Code.

code .

Some Project Notes

The project generation creates a ReadMe.html in the root of the project. Make sure and check it out. It has a list of pre-requisites needed for the project as well as a lot of good information on general good practices.

We aren’t going to dig too far into the project itself in this post, but it is helpful to know where the data lives and what it looks like for when we are trying out some GraphQL queries. The backing data is in a static class found in the Repositories/Database.cs file.

The data is Star Wars themed and consists of two lists of characters one for droid and one for humans which get combined into a list of characters. The following is the Database class for reference.

public static class Database
{
    static Database()
    {
        Droids = new List<Droid>()
        {
            new Droid()
            {
                Id = new Guid("1ae34c3b-c1a0-4b7b-9375-c5a221d49e68"),
                Name = "R2-D2",
                Friends = new List<Guid>()
                {
                    new Guid("94fbd693-2027-4804-bf40-ed427fe76fda"),
                    new Guid("c2bbf949-764b-4d4f-bce6-0404211810fa")
                },
                AppearsIn = new List<Episode>() { Episode.NEWHOPE,
                                                  Episode.EMPIRE,
                                                  Episode.JEDI, },
                PrimaryFunction = "Astromech"
            },
            new Droid()
            {
                Id = new Guid("c2bbf949-764b-4d4f-bce6-0404211810fa"),
                Name = "C-3PO",
                Friends = new List<Guid>(),
                AppearsIn = new List<Episode>() { Episode.NEWHOPE,
                                                  Episode.EMPIRE,
                                                  Episode.JEDI, },
                PrimaryFunction = "Protocol"
            }
        };
        Humans = new List<Human>()
        {
            new Human()
            {
                Id = new Guid("94fbd693-2027-4804-bf40-ed427fe76fda"),
                Name = "Luke Skywalker",
                Friends = new List<Guid>()
                {
                    new Guid("1ae34c3b-c1a0-4b7b-9375-c5a221d49e68"),
                    new Guid("c2bbf949-764b-4d4f-bce6-0404211810fa")
                },
                AppearsIn = new List<Episode>() { Episode.NEWHOPE,
                                                  Episode.EMPIRE,
                                                  Episode.JEDI, },
                HomePlanet = "Tatooine"
            },
            new Human()
            {
                Id = new Guid("7f7bf389-2cfb-45f4-b91e-9d95441c1ecc"),
                Name = "Darth Vader",
                Friends = new List<Guid>(),
                AppearsIn = new List<Episode>() { Episode.NEWHOPE,
                                                  Episode.EMPIRE,
                                                  Episode.JEDI, },
                HomePlanet = "Tatooine"
            }
        };
        Characters = Droids.AsEnumerable<Character>()
                           .Concat(Humans)
                           .ToList();
    }

    public static List<Character> Characters { get; }

    public static List<Droid> Droids { get; }

    public static List<Human> Humans { get; }
}

Try it out

When you run the project in development mode (the default) it will show a GraphQL playground which is made available by GraphQL.NET. It looks like the following.

Box 1 is the area where you enter the query you want to execute against the GraphQL backend. Box 2 is the play button which sends the query to the backend. Finally, box 3 is where the results of the query are displayed.

The following query is asking for ID, Name, and Appears In properties for the human that matches the provided ID.

query getHuman{
  human(id: "94fbd693-2027-4804-bf40-ed427fe76fda")
  {
    id,
    name,
    appearsIn    
  }
}

On our sample data, the query returns the following.

{
  "data": {
    "human": {
      "id": "94fbd693-2027-4804-bf40-ed427fe76fda",
      "name": "Luke Skywalker",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ]
    }
  }
}

Now let’s try creating a new human. Clear the query area and enter the following query.

mutation createHuman($human: HumanInput!) {
  createHuman(human: $human) {
    id
    name
  }
}

If you tried to run the above it would fail. For this query to work we need to define what $human is. You do this in the Query Variables area which is right below box 1 in the screenshot above. Enter the following and hit the play button.

{
  "human": {
    "name": "Eric Anderson",
    "homePlanet": "Earth"
  }
}

This will result in the following. Your ID will be different of course.

{
  "data": {
    "createHuman": {
      "id": "22297c0e-01b4-4322-8e25-16d455a0c8e2",
      "name": "Eric Anderson"
    }
  }
}

Wrapping Up

The above information is enough to get started playing with GraphQL with ASP.NET Core. There is a lot more that I want to dig into so look for more posts on these topics. The code can be found here.

---

Also published on Medium.