GraphQLinq.Client 1.1.0-beta

This is a prerelease version of GraphQLinq.Client.
dotnet add package GraphQLinq.Client --version 1.1.0-beta
NuGet\Install-Package GraphQLinq.Client -Version 1.1.0-beta
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="GraphQLinq.Client" Version="1.1.0-beta" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GraphQLinq.Client --version 1.1.0-beta
#r "nuget: GraphQLinq.Client, 1.1.0-beta"
#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 GraphQLinq.Client as a Cake Addin
#addin nuget:?package=GraphQLinq.Client&version=1.1.0-beta&prerelease

// Install GraphQLinq.Client as a Cake Tool
#tool nuget:?package=GraphQLinq.Client&version=1.1.0-beta&prerelease

GraphQLinq

LINQ to GraphQL - Strongly typed GraphQL queries with LINQ query syntax.

You must regenerate your client code with GraphQLinq.Scaffolding after updating GraphQLinq.Client to a newer version

Project Icon

About The Project

GraphQLinq is a .NET tool for generating C# classes from a GraphQL endpoint and a .Net Standard library for writing strongly typed GraphQL queries with LINQ.

With GraphQLinq you will:

  • Write strongly typed queries with LINQ.
  • Have your queries checked by the compiler.
  • Run queries and deserialize JSON response into strongly typed classes in a single method call.
  • View queries generated by LINQ to GraphQL.

Getting Started

Install Scaffolding Tool

Before you starting writing queries, you need to generate classes from GraphQL types. This is done by GraphQLinq.Scaffolding, a .NET tool that is part of this project.

To get the tool, open your favourite command shell and run

dotnet tool install --global --version 1.1.0-beta GraphQLinq.Scaffolding

Running this command will install the GraphQLinq.Scaffolding tool and make it available globally for all projects.

Scaffolding Client Code

Next, navigate to the project where you want to add the classes and scaffold the client code. In this example, I will use the SpaceX GraphQL Api so run the following command:

graphqlinq-scaffold https://api.spacex.land/graphql -o SpaceX -n SpaceX

The o option specifies the output directory for generated classes, and n specifies the namespace of the classes.

Scaffolding

Install GraphQLinq NuGet Package

Before writing the queries, you need to install the LINQ to GraphQL client library from NuGet. Run the following command to install it in the current project:

dotnet add package GraphQLinq.Client --version 1.1.0-beta

Running GraphQL Queries with LINQ

The scaffolding tool generates classes for types available in the GraphQL type system and a QueryContext class that serves as an entry point for running the queries. GraphQLinq supports running different kinds of queries.

Query all Primitive Properties of a Type

To query all properties of a type, simply run a query like this:

var spaceXContext = new QueryContext();

var company = await spaceXContext.Company().ToItem();

RenderCompanyDetails(company);

This will query all primitive and string properties of Company, but it won't query nested properties or collection type properties.

Query Specific Properties

If you want to query specific properties, including a navigation property, you can specify it with the Select method. You either map the projection to an existing type or an anonymous object (Headquarters is a nested property):

var companySummaryAnonymous = await spaceXContext.Company().Select(c => new { c.Ceo, c.Name, c.Headquarters }).ToItem();

//Use data class to select specific properties
var companySummary = await spaceXContext.Company().Select(c => new CompanySummary
{
    Ceo = c.Ceo,
    Name = c.Name,
    Headquarters = c.Headquarters
}).ToItem();

RenderCompanySummary(companySummary);

Include Navigation Properties

You can also query navigation properties using the Include method. You can include several properties if you need, and you can also Include nested navigation properties:

var companyWithHeadquartersAndLinks = await spaceXContext.Company()
                                            .Include(info => info.Headquarters)
                                            .Include(info => info.Links).ToItem();

RenderCompanyDetailsAndLinks(companyWithHeadquartersAndLinks);

Pass Parameters to Queries and Compose Queries

If the query has parameters, the generated method will have a parameter for each query parameter.

This code will query for all Missions that included Orbital ATK as a manufacturer. It also builds a new query over the existing one that includes Payloads in the result.

var missionsQuery = spaceXContext.Missions(new MissionsFind { Manufacturer = "Orbital ATK" }, null, null)
                                 .Include(mission => mission.Manufacturers);
var missions = missionsQuery.ToEnumerable();

RenderMissions(missions);

var missionsWithPayloads = await missionsQuery.Include(mission => mission.Payloads).ToEnumerable();

RenderMissions(missionsWithPayloads, true);

Include Multiple Levels of Navigation Properties

The Include method allows quering for multi-level nested properties too. For example, here is how to query for Launches and include Rocket's second stage payload manufacturer:

//Launch_date_unix and Static_fire_date_unix need custom converter
spaceXContext.JsonSerializerOptions.Converters.Add(new UnixEpochDateTimeConverter());

var launches = await spaceXContext.Launches(null, 10, 0, null, null)
                            .Include(launch => launch.Links)
                            .Include(launch => launch.Rocket)
                            .Include(launch => launch.Rocket.Second_stage.Payloads.Select(payload => payload.Manufacturer))
                            .ToEnumerable();

RenderLaunches(launches);

View Generated Query

You can view the GraphQL query and variables by using the Query and Variables property of the GraphQuery class. The ToString() method of the GraphQuery class returns the query and the variables combined:

var missionsQuery = spaceXContext.Missions(new MissionsFind { Manufacturer = "Orbital ATK" }, null, null)
                                 .Include(mission => mission.Manufacturers);

var query = missionsQuery.Query;
var fullQuery = missionsQuery.ToString();

If you run the above code query will be equal to

query ($find: MissionsFind) { result: missions (find: $find) { 
  description
  id
  name
  twitter
  website
  wikipedia
  manufacturers
 }}

and the content of fullQuery will be:

{"query":"query ($find: MissionsFind) { result: missions (find: $find) { 
  description
  id
  name
  twitter
  website
  wikipedia
  manufacturers
 }}","variables":{"find":{"manufacturer":"Orbital ATK"}}}

Roadmap

See the open issues for a list of proposed features and known issues.

Contributing

If you encounter a bug or have a feature request, please use the Issue Tracker. The project is also open to contributions, so feel free to fork the project and open pull requests.

License

Copyright © Giorgi Dalakishvili

Distributed under the Apache License. See License for more information.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  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 was computed.  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 was computed.  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 was computed.  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

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.0-beta 12,746 7/9/2022
1.0.1-beta 1,489 4/28/2021
1.0.0-beta 187 4/26/2021

Added suppport for async/await.
     Migrated from WebClient to HttpClient.
     Migrated from Newtonsoft.Json to System.Text.Json