Skip to content

GraphQL

  • Yet another communication standard
  • Mainly for client ⇔ server
  • GraphQL is typically served over HTTP
    • Contrary to REST we use a single endpoint
  • GraphQL services typically respond using JSON (yet not required by the spec)

With GraphQL you think of data as a graph of nodes.


GraphQL has its own language to query data

{
rewards {
title
}
}
{
rewards(id: 1) {
title,
savings {
amount
}
}
}

  • GraphQL gives power to the client.
  • The client can specify what they want exactly for a specific use-case.
    • The server needs to be implemented in a way that supports the queries.
  • This leads to very targeted queries fetching only the information that is needed.

Using HotChocolate1

NuGet:

Terminal window
Install-Package HotChocolate.AspNetCore
Install-Package HotChocolate.Data
Install-Package GraphQL.Server.Transports.AspNetCore

public class Query
{
public IQueryable<Reward> GetRewards =>
new List<Reward>().AsQueryable();
}

The methods can return any data. We just return an empty list here to get started.


Program.cs
// Type Query points to Query class (previous slide)
builder.Services.AddGraphQLServer().AddQueryType<Query>()
// ...
app.MapGraphQL(path: "/graphql");

Run application and go to route /graphql in the browser.

Create a new document and try out the following query.

query MyQuery {
getRewards {
title
}
}

Should yield result:

{
"data": {
"getRewards": []
}
}

public class Query
{
[UseProjection]
[UseFiltering]
[UseSorting]
public IQueryable<Reward> GetRewards(
[Service] RewardDbContext context) =>
context.Rewards;
}
Program.cs
builder.Services.AddGraphQLServer().AddQueryType<Query>()
.AddProjections().AddFiltering().AddSorting();

query GetRewards {
rewards {
title
}
}

returns

{
"data": {
"rewards": [
{
"title": "X-Jam"
}
]
}
}

public class Query
{
[UseFirstOrDefault]
[UseProjection]
public IQueryable<Reward?> GetReward(
[Service] RewardDbContext context,
int id) =>
context.Rewards.Where(r => r.Id == id);
}
query GetReward {
reward(id: 1) {
title
}
}
{
"data": {
"reward": {
"title": "X-Jam"
}
}
}

Using StrawberryShake2

Terminal window
# in root folder of solution
dotnet new tool-manifest
dotnet tool install StrawberryShake.Tools
# in Blazor Client project
Install-Package StrawberryShake.Blazor

Terminal window
# server needs to run for this command
# run command in root folder of solution
# use whatever url your server is serving from
dotnet graphql init https://localhost:7232/graphql/ `
-n RewardClient ` # give your generated client a name
-p SavingsPlanner/Client # point to the client project

.graphqlrc.json
{
"schema": "schema.graphql",
"documents": "**/*.graphql",
"extensions": {
"strawberryShake": {
"name": "RewardClient",
"namespace": "SavingsPlanner.Client.GraphQL",
"url": "https://localhost:7232/graphql/",
//...
}
}
}

GetRewards.graphql
query GetRewards {
rewards {
title,
description,
targetAmount,
id
}
}

Terminal window
dotnet build

Program.cs
builder.Services
.AddRewardClient()
.ConfigureHttpClient(client =>
client.BaseAddress = new Uri(
builder.HostEnvironment.BaseAddress + "graphql"));

@inject RewardClient RewardClient
// ...
await RewardClient.GetRewards.ExecuteAsync();

GraphQL Mutations let you modify data.

mutation MyMutation {
addReward(reward: {
title: "Apple",
description: "fruit",
targetAmount: 1337,
savingStart: "2023-03-01T00:00:00.000+01:00",
savingEnd: "2023-04-01T00:00:00.000+01:00",
}) {
title,
id
}
}

You send the data and have control of what you get back.


public class Mutation
{
public async Task<RewardListItemDto> AddReward(
[Service] IRepository<Reward> rewardRepository,
AddRewardDto reward)
{
return await rewardRepository
.AddAsync<AddRewardDto, RewardListItemDto>(reward);
}
}

It is recommended to create specific types for adding items (e.g. without ID property).


Program.cs
builder.Services
.AddGraphQLServer()
// ... your queries
.AddMutationType<Mutation>();

Terminal window
# run from Client directory
# server needs to run
# correct server address needs to be specified in .graphqlrc
dotnet graphql update

AddReward.graphql
mutation AddReward($rewardInput: AddRewardDtoInput!) {
addReward(reward: $rewardInput) {
id
}
}

Terminal window
dotnet build

NewReward.razor
@inject RewardClient RewardClient
// ...
await RewardClient.AddReward.ExecuteAsync(
new AddRewardDtoInput()
{
Title = _title,
TargetAmount = _targetAmount,
SavingStart = _startDate.Value,
SavingEnd = _endDate.Value,
Description = _description
});

GraphQL offers an easy way to subscribe to events.
The Server can notify the client of changes via a websocket connection.


public class Subscription
{
[Subscribe]
public RewardListItemDto RewardAdded(
[EventMessage] RewardListItemDto reward)
=> reward;
}

public async Task<RewardListItemDto> AddReward(
[Service] IRepository<Reward> rewardRepository,
[Service] ITopicEventSender sender,
AddRewardDto reward)
{
var addedReward = await rewardRepository
.AddAsync<AddRewardDto, RewardListItemDto>(reward);
await sender.SendAsync(
nameof(Subscription.RewardAdded), addedReward);
return addedReward;
}

Program.cs
builder.Services
.AddGraphQLServer()
// ... queries and mutations
.AddInMemorySubscriptions()
.AddSubscriptionType<Subscription>();
// ...
app.UseRouting();
app.UseWebSockets(); // add this line below UseRouting

subscription MySubscription {
rewardAdded {
id,
title
}
}

Terminal window
# run from Client directory
# server needs to run
# correct server address needs to be specified in .graphqlrc
dotnet graphql update
# Add NuGet Package
Install-Package StrawberryShake.Transport.WebSockets

SubscribeRewardAdded.graphql
subscription SubscribeRewardAdded {
rewardAdded {
id,
title,
description,
targetAmount,
}
}

Build project to regenerate client afterwards.


Program.cs
var graphQlUri = new Uri(
builder.HostEnvironment.BaseAddress + "graphql");
var graphQlWebSocketUri = new UriBuilder(graphQlUri)
{
Scheme = Uri.UriSchemeWss
}.Uri;
builder.Services.AddRewardClient()
.ConfigureHttpClient(client =>
client.BaseAddress = graphQlUri)
.ConfigureWebSocketClient(client =>
client.Uri = graphQlWebSocketUri);

Rewards.razor
@implements IDisposable
// ...
private IDisposable? rewardAddedSubscription;
protected override async Task OnInitializedAsync()
{
await LoadDataAsync();
rewardAddedSubscription = RewardClient
.SubscribeRewardAdded
.Watch()
.Subscribe(message =>
{
var dto = new RewardListItemDto(
message.Data.RewardAdded.Id,
message.Data.RewardAdded.Title,
message.Data.RewardAdded.TargetAmount,
message.Data.RewardAdded.Description);
rewards.Add(dto);
StateHasChanged();
});
}
public void Dispose()
{
bookAddedSubscription?.Dispose();
}
  1. Get started with GraphQL in .NET Core

  2. Get started with Strawberry Shake and Blazor