In this blog post, we\u2019ll discuss setting up your environment, defining schemas, generating client code, and seamlessly integrating it all into a sample project. Here we go!<\/p>\n\n\n
What is GraphQL?<\/h2>\n\n\n\n
Before we dig into building a sample application, let\u2019s quickly recap GraphQL and its benefits. GraphQL<\/a>, developed by Facebook in 2012 and open-sourced in 2015, is a query language for APIs and a runtime for executing queries based on a user-defined type system.<\/p>\n\n\n\n If you have been a .NET developer for a while, you may have already worked with OData<\/a>. Conceptually, GraphQL is similar in that it lets you request exactly the data you need from an API, eliminating the typical over-fetching or under-fetching issues you may see in REST APIs. For example, in a typical REST API, you may want to retrieve customer data and either need to make a second request to get their address details or always get the address details in the response, even when they\u2019re not always required..<\/p>\n\n\n\n Unlike most REST APIs, a GraphQL API exposes a single endpoint you can query for any data you need. The endpoint can define several operations, all of which are self-documenting through a schema. A schema provides a comprehensive and queryable description of the API structure, types, and available operations. The schema also defines types and relationships between them, ensuring clients know exactly what data is available and receive helpful error messages when things go wrong.<\/p>\n\n\n\n There are a few concepts to keep in mind throughout this post:<\/p>\n\n\n\n One more thing to cover: when implementing a GraphQL API, you have two transport protocols to consider for data exchange: HTTP and WebSockets. HTTP is typically used for traditional query and mutation operations, where clients send HTTP On the other hand, WebSockets are used for real-time applications requiring instant updates, such as live chat, online gaming, or real-time dashboards. GraphQL subscriptions use WebSockets to maintain a persistent connection between the client and the server, enabling the server to push updates to the client as soon as data changes occur. This reduces latency and provides a more responsive user experience compared to polling mechanisms often used with HTTP.<\/p>\n\n\n\n Choosing between HTTP and WebSockets depends on your application’s specific requirements. For most standard operations, HTTP is sufficient and simpler to implement. However, for real-time data updates, integrating WebSockets with GraphQL subscriptions can significantly enhance your application\u2019s interactivity and responsiveness. Also, both transports can be used in conjunction when building solutions. In this post, we\u2019ll use an HTTP endpoint as our example to work with.<\/p>\n\n\n Note:<\/strong> If you want to learn more about how REST, GraphQL, and gRPC compare, check out this talk from JetBrains .NET Days Online by Poornima Nayar<\/a>.<\/p>\n <\/div>\n \n\n\n\n\n\n\n Now, let\u2019s talk about StrawberryShake<\/a>. This open-source .NET library simplifies building GraphQL clients by generating strongly-typed client-side code from your GraphQL schema and queries. This means less boilerplate and more focus on what matters \u2013 your application logic.<\/p>\n\n\n\n It uses source generators to generate all the client-side code based on the GraphQL schema you define or introspect from a GraphQL API.<\/p>\n\n\n\n Let\u2019s transition into a practical example. First, let\u2019s make sure you have the GraphQL plugin installed in JetBrains Rider<\/a>. This plugin is necessary for providing syntax highlighting, validation, and auto-completion for GraphQL schemas and queries, streamlining your development process.<\/p>\n\n\n\n Open JetBrains Rider and bring up the Settings\/Preferences<\/strong> menu. Go to Plugins<\/strong> in the left-hand sidebar, and search for “GraphQL” in the Marketplace<\/strong> tab. Click Install<\/strong> to add the plugin to your Rider setup. You may need to restart Rider to activate the plugin.<\/p>\n\n\n\n We\u2019re ready to jump into creating our project and setting everything up in JetBrains Rider. Let’s get to work!<\/p>\n\n\n\n Let\u2019s look at what we\u2019ll build first. Since we\u2019re focusing on building a GraphQL client<\/em>, we\u2019ll need an API to interact with. We\u2019re in luck, because there are plenty of GraphQL APIs available<\/a>. In this blog post, we\u2019ll use Trevor Blades\u2019 Countries GraphQL API<\/a>, which provides data about countries around the world. The sample application will be a page that shows information about the countries included in that API, and a way to get more details for each.<\/p>\n\n\n\n The countries API endpoint is available at https:\/\/countries.trevorblades.com\/<\/a>, which exposes a playground where you can test your queries against it.<\/p>\n\n\n Note:<\/strong> Michael Staib, founder of ChilliCream (the company that also builds the StrawberryShake project we use in this blog post) was a guest in one of our livestreams to talk about building a GraphQL server with ASP.NET Core and HotChocolate<\/a>.<\/p>\n <\/div>\n \n\n\n\n\n\n\n In JetBrains Rider, create a new Web App project using the Razor Pages template. Give it a name, such as the very original \u201cCountries\u201d I used here:<\/p>\n\n\n\n While not required, for this sample, I removed some of the default CSS in the project and included PicoCSS<\/a> \u2013 a great small CSS framework that makes any web page look nice. Here\u2019s my updated You can also clone a copy of this project from GitHub<\/a>, and explore individual commits if you want to follow along.<\/p>\n\n\n\n Time for GraphQL! In your C# project, use the context menu to add a new GraphQL Config<\/strong> file and paste the following contents into it:<\/p>\n\n\n\n This In the left-hand gutter, right next to the production endpoint, you\u2019ll see a Run<\/strong> icon:<\/p>\n\n\n\n Click it to run an introspection of the remote schema. When you do, you\u2019ll see a popup that lets you enter an authorization token. You can skip it, but this is why I added the When finished, a The toolbar also contains a Run<\/strong> button, which is not very useful yet. Let\u2019s change that! In our application, I\u2019d like to show a list of all countries with their country code, name, and flag image. Add a new file called This snippet defines a GraphQL query (named \u201cListCountries\u201d) that retrieves information from a collection on the API endpoint called \u201ccountries\u201d. This query returns an array of Country elements, and each contains the code, name, and emoji. Note that you can Cmd+Click<\/kbd> or Ctrl+Click<\/kbd> on the name to navigate to the schema\u2019s definition of available data and collections.<\/p>\n\n\n\n Now is a good time to try the Run<\/strong> button in the editor. You\u2019ll see Rider opens a tool window showing the query result:<\/p>\n\n\n\n While we\u2019re creating queries in Rider, let\u2019s add one more file: This query will be used in our sample application to display details for a specific country. The query is named Another interesting bit in this query is that we\u2019re not only fetching the country data but also its related continent. If you do not need that data, you can keep it out of the query and get a smaller response payload size. You will also see the fields queried for a continent are defined as a With those two queries defined, let\u2019s continue building our ASP.NET Core application.<\/p>\n\n\n\n To start generating the C# client for the countries GraphQL schema we just queried, you will need to add a NuGet package reference to \n
POST<\/code>, PUT<\/code>, or DELETE<\/code> in REST<\/code>.<\/li>\n\n\n\nGET<\/code> and POST<\/code> requests to the GraphQL server and receive responses containing the requested data. This method is straightforward and works well for most cases where data changes are infrequent or do not need to be immediately reflected on the client.<\/p>\n\n\n\nWhat is StrawberryShake?<\/h2>\n\n\n\n
Prerequisites<\/h2>\n\n\n\n
![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/08\/image-67.png\")
<\/figure>\n\n\n\nCreating the project in Rider<\/h2>\n\n\n\n
![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/08\/image-68.png\")
<\/figure>\n\n\n\n_Layout.cshtml<\/code>:<\/p>\n\n\n\n<!doctype html>\n<html lang=\"en\">\n<head>\n <meta charset=\"utf-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n <meta name=\"color-scheme\" content=\"light dark\">\n <link rel=\"stylesheet\" href=\"https:\/\/cdn.jsdelivr.net\/npm\/@@picocss\/pico@2\/css\/pico.min.css\" \/>\n <link rel=\"stylesheet\" href=\"~\/css\/site.css\" asp-append-version=\"true\" \/>\n <title>@ViewData[\"Title\"] - Countries<\/title>\n<\/head>\n<body>\n<main class=\"container\">\n <header>\n <nav>\n <ul>\n <li><strong>Countries<\/strong><\/li>\n <\/ul>\n <ul>\n <li><a href=\"\/\">Index<\/a><\/li>\n <\/ul>\n <\/nav>\n <\/header>\n @RenderBody()\n<\/main>\n\n\n<script src=\"~\/js\/site.js\" asp-append-version=\"true\"><\/script>\n\n\n@await RenderSectionAsync(\"Scripts\", required: false)\n<script type=\"module\" defer>\n import { polyfillCountryFlagEmojis } from \"https:\/\/cdn.skypack.dev\/country-flag-emoji-polyfill\";\n polyfillCountryFlagEmojis();\n<\/script>\n<\/body>\n<\/html><\/pre>\n\n\n\nWorking with GraphQL in Rider<\/h2>\n\n\n\n
schema: schema.graphql\nextensions:\n endpoints:\n production:\n url: https:\/\/countries.trevorblades.com\/graphql\/\n headers:\n Authorization: Bearer ${TOKEN}\ndocuments: '**\/*.graphql'<\/pre>\n\n\n\ngraphql.config.yml<\/code> file will be used by Rider to access the schema for the countries API, and generate queries that can be executed inside the IDE. This configuration file also defines one or more endpoints, and potential headers required to access an endpoint, such as authorization headers. The countries API doesn\u2019t require authentication, but we\u2019ll see in a second why I added it here anyways.<\/p>\n\n\n\n![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/08\/image-69.png\")
<\/figure>\n\n\n\n${TOKEN}<\/code> placeholder earlier: to show you how to add variables into the GraphQL configuration.<\/p>\n\n\n\nschema.graphql<\/code> file is automatically added to your project, listing all the types, fields, and operations exposed by the countries API. Note the toolbar at the top of the editor: you can switch to a different endpoint if you have e.g. a staging and production GraphQL API to work with, and there\u2019s a Refresh<\/strong> button to re-run schema introspection and update the types, fields, and operations in the API.<\/p>\n\n\n\n![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/08\/image-70.png\")
<\/figure>\n\n\n\nlistcountries.graphql<\/code>, and paste the following query into it:<\/p>\n\n\n\nquery ListCountries {\n countries {\n code\n name\n emoji\n }\n}<\/pre>\n\n\n\n![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/08\/image-71.png\")
<\/figure>\n\n\n\ngetcountry.graphql<\/code>, and paste the following contents into it:<\/p>\n\n\n\nuery GetCountry($countryCode: ID!) {\n country(code: $countryCode) {\n code\n name\n emoji\n capital\n currency\n languages {\n code\n name\n }\n ...Continent\n }\n}\n\n\nfragment Continent on Country {\n continent {\n code\n name\n }\n}<\/pre>\n\n\n\nGetCountry<\/code>, and requires a parameter $countryCode<\/code>. It then requests data from the GraphQL API, requesting a country (by $countryCode<\/code>) and returning various fields of information from it.<\/p>\n\n\n\nfragment<\/code>. This is a way to make your GraphQL queries a bit more maintainable, as including the Continent<\/code> on any query that works with Country<\/code> now only means adding ...Continent<\/code> and not the complete list of fields. This is not a requirement, and you can also write the entire query like this:<\/p>\n\n\n\nquery GetCountry($countryCode: ID!) {\n country(code: $countryCode) {\n code\n name\n emoji\n capital\n currency\n languages {\n code\n name\n }\n continent {\n code\n name\n }\n }\n}<\/pre>\n\n\n\nAdding StrawberryShake GraphQL source generation<\/h2>\n\n\n\n
StrawberryShake.Server<\/a><\/code>. While named \u201cserver\u201d, this package includes additional dependencies. to get you started with creating a GraphQL client.<\/p>\n\n\n\n
![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/08\/image-72.png\")
<\/figure>\n\n\n\n![\"\"](\"https:\/\/blog.jetbrains.com\/wp-content\/uploads\/2024\/08\/image-73.png\")
<\/figure>\n\n\n\n