GraphQL.Client 6.1.0

dotnet add package GraphQL.Client --version 6.1.0                
NuGet\Install-Package GraphQL.Client -Version 6.1.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GraphQL.Client" Version="6.1.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GraphQL.Client --version 6.1.0                
#r "nuget: GraphQL.Client, 6.1.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install GraphQL.Client as a Cake Addin
#addin nuget:?package=GraphQL.Client&version=6.1.0

// Install GraphQL.Client as a Cake Tool
#tool nuget:?package=GraphQL.Client&version=6.1.0                

GraphQL.Client

A GraphQL Client for .NET Standard over HTTP.

Provides the following packages:

Package Downloads Nuget Latest
GraphQL.Client Nuget Nuget
GraphQL.Client.Abstractions Nuget Nuget
GraphQL.Client.Abstractions.Websocket Nuget Nuget
GraphQL.Client.LocalExecution Nuget Nuget
GraphQL.Client.Serializer.Newtonsoft Nuget Nuget
GraphQL.Client.Serializer.SystemTextJson Nuget Nuget
GraphQL.Primitives Nuget Nuget

Specification

The Library will try to follow the following standards and documents:

Usage

The intended use of GraphQLHttpClient is to keep one instance alive per endpoint (obvious in case you're operating full websocket, but also true for regular requests) and is built with thread-safety in mind.

Create a GraphQLHttpClient

// To use NewtonsoftJsonSerializer, add a reference to 
// NuGet package GraphQL.Client.Serializer.Newtonsoft
var graphQLClient = new GraphQLHttpClient(
    "https://api.example.com/graphql", 
    new NewtonsoftJsonSerializer());

[!NOTE] GraphQLHttpClient is meant to be used as a single long-lived instance per endpoint (i.e. register as singleton in a DI system), which should be reused for multiple requests.

Create a GraphQLRequest:

Simple Request:
var heroRequest = new GraphQLRequest {
    Query = """
    {
        hero {
            name
        }
    }
    """
};
OperationName and Variables Request:
var personAndFilmsRequest = new GraphQLRequest {
    Query ="""
    query PersonAndFilms($id: ID) {
        person(id: $id) {
            name
            filmConnection {
                films {
                    title
                }
            }
        }
    }
    """,
    OperationName = "PersonAndFilms",
    Variables = new {
        id = "cGVvcGxlOjE="
    }
};

[!WARNING] Be careful when using byte[] in your variables object, as most JSON serializers will treat that as binary data.

If you really need to send a list of bytes with a byte[] as a source, then convert it to a List<byte> first, which will tell the serializer to output a list of numbers instead of a base64-encoded string.

Execute Query/Mutation

public class ResponseType 
{
    public PersonType Person { get; set; }
}

public class PersonType 
{
    public string Name { get; set; }
    public FilmConnectionType FilmConnection { get; set; }    
}

public class FilmConnectionType {
    public List<FilmContentType> Films { get; set; }    
}

public class FilmContentType {
    public string Title { get; set; }
}

var graphQLResponse = await graphQLClient.SendQueryAsync<ResponseType>(personAndFilmsRequest);

var personName = graphQLResponse.Data.Person.Name;

Using the extension method for anonymously typed responses (namespace GraphQL.Client.Abstractions) you could achieve the same result with the following code:

var graphQLResponse = await graphQLClient.SendQueryAsync(
    personAndFilmsRequest, 
    () => new { person = new PersonType()});
var personName = graphQLResponse.Data.person.Name;

[!IMPORTANT] Note that the field in the GraphQL response which gets deserialized into the response object is the data field.

A common mistake is to try to directly use the PersonType class as response type (because thats the thing you actually want to query), but the returned response object contains a property person containing a PersonType object (like the ResponseType modelled above).

Use Subscriptions

public class UserJoinedSubscriptionResult {
    public ChatUser UserJoined { get; set; }

    public class ChatUser {
        public string DisplayName { get; set; }
        public string Id { get; set; }
    }
}
Create subscription
var userJoinedRequest = new GraphQLRequest {
    Query = @"
    subscription {
        userJoined{
            displayName
            id
        }
    }"
};

IObservable<GraphQLResponse<UserJoinedSubscriptionResult>> subscriptionStream 
    = client.CreateSubscriptionStream<UserJoinedSubscriptionResult>(userJoinedRequest);

var subscription = subscriptionStream.Subscribe(response => 
    {
        Console.WriteLine($"user '{response.Data.UserJoined.DisplayName}' joined")
    });
End Subscription
subscription.Dispose();

Automatic persisted queries (APQ)

Automatic persisted queries (APQ) are supported since client version 6.1.0.

APQ can be enabled by configuring GraphQLHttpClientOptions.EnableAutomaticPersistedQueries to resolve to true.

By default, the client will automatically disable APQ for the current session if the server responds with a PersistedQueryNotSupported error or a 400 or 600 HTTP status code. This can be customized by configuring GraphQLHttpClientOptions.DisableAPQ.

To re-enable APQ after it has been automatically disabled, GraphQLHttpClient needs to be disposed an recreated.

APQ works by first sending a hash of the query string to the server, and only sending the full query string if the server has not yet cached a query with a matching hash. With queries supplied as a string parameter to GraphQLRequest, the hash gets computed each time the request is sent.

When you want to reuse a query string (propably to leverage APQ 😉), declare the query using the GraphQLQuery class. This way, the hash gets computed once on construction of the GraphQLQuery object and handed down to each GraphQLRequest using the query.

GraphQLQuery query = new("""
                         query PersonAndFilms($id: ID) {
                             person(id: $id) {
                                 name
                                 filmConnection {
                                     films {
                                         title
                                     }
                                 }
                             }
                         }
                         """);
                         
var graphQLResponse = await graphQLClient.SendQueryAsync<ResponseType>(
    query, 
    "PersonAndFilms",
    new { id = "cGVvcGxlOjE=" });

Syntax Highlighting for GraphQL strings in IDEs

.NET 7.0 introduced the StringSyntaxAttribute to have a unified way of telling what data is expected in a given string or ReadOnlySpan<char>. IDEs like Visual Studio and Rider can then use this to provide syntax highlighting and checking.

From v6.0.4 on all GraphQL string parameters in this library are decorated with the [StringSyntax("GraphQL")] attribute.

Currently, there is no native support for GraphQL formatting and syntax highlighting in Visual Studio, but the GraphQLTools Extension provides that for you.

For Rider, JetBrains provides a Plugin, too.

To leverage syntax highlighting in variable declarations, use the GraphQLQuery class.

Blazor WebAssembly Limitations

Blazor WebAssembly differs from other platforms as it does not support all features of other .NET runtime implementations. For instance, the following WebSocket options properties are not supported and will not be set:

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (100)

Showing the top 5 NuGet packages that depend on GraphQL.Client:

Package Downloads
GraphQL.Client.Extensions

Extensions for GraphQL.Client to build graphQL queries from a C# model.

Speckle.Core

Core is the .NET SDK for Speckle

Queryout.SmartGateway.Sdk

Package Description

Trackmatic.Client

.Net rest client library for Trackmatic rest api

Logibricks.Utility

Package Description

GitHub repositories (14)

Showing the top 5 popular GitHub repositories that depend on GraphQL.Client:

Repository Stars
Squidex/squidex
Headless CMS and Content Managment Hub
phongnguyend/Practical.CleanArchitecture
Full-stack .Net 8 Clean Architecture (Microservices, Modular Monolith, Monolith), Blazor, Angular 18, React 18, Vue 3, BFF with YARP, Domain-Driven Design, CQRS, SOLID, Asp.Net Core Identity Custom Storage, OpenID Connect, Entity Framework Core, OpenTelemetry, SignalR, Hosted Services, Health Checks, Rate Limiting, Cloud Services (Azure, AWS, GCP).
0x5bfa/FluentHub
A stylish yet powerful GitHub client for Windows
getsentry/sentry-dotnet
Sentry SDK for .NET
sharpenrocks/Sharpen
Visual Studio extension that intelligently introduces new C# features into your existing codebase
Version Downloads Last updated
6.1.0 956,380 5/21/2024
6.0.5 218,833 4/22/2024
6.0.4 5,164 4/22/2024
6.0.3 285,086 3/20/2024
6.0.2 1,333,054 11/23/2023
6.0.1 538,593 9/29/2023
6.0.0 2,029,816 4/13/2023
5.1.1 1,686,744 1/23/2023
5.1.0 2,668,905 8/1/2022
5.0.2 820,955 7/19/2022
5.0.1 23,525 7/18/2022
5.0.0 36,279 7/15/2022
4.0.2 5,032,293 12/16/2021
4.0.1 507,705 10/29/2021
4.0.0 165,984 10/27/2021
3.2.4 2,989,853 6/6/2021
3.2.3 1,635,068 4/2/2021
3.2.2 296,865 3/2/2021
3.2.1 568,217 1/7/2021
3.2.0 775,804 10/15/2020
3.1.9 654,731 9/17/2020
3.1.8 2,449 9/17/2020
3.1.7 3,916 9/15/2020
3.1.6 161,141 8/27/2020
3.1.5 89,980 8/24/2020
3.1.4 62,528 8/15/2020
3.1.3 516,898 6/22/2020
3.1.2 235,172 5/29/2020
3.1.1 15,771 5/26/2020
3.1.0 324,751 4/21/2020
3.0.3 16,646 4/19/2020
3.0.2 61,474 4/16/2020
3.0.1 75,832 3/26/2020
3.0.0 7,289 3/23/2020
2.1.2 131,599 3/9/2020
2.1.0 16,087 2/21/2020
2.0.0 53,052 2/7/2020
2.0.0-beta0011 592 2/7/2020
2.0.0-alpha.3 427,253 11/6/2018
2.0.0-alpha.2 83,685 9/13/2018
2.0.0-alpha.1 1,226 8/27/2018
1.0.3 3,003,695 5/7/2018
1.0.2 91,072 3/12/2018
1.0.1 30,202 1/27/2018
1.0.0 18,788 12/20/2017
1.0.0-beta3 1,082 12/17/2017
1.0.0-beta2 1,082 12/11/2017
1.0.0-beta1 1,038 12/10/2017