From 90e2826554be797eae77344e5704cc0b523973c3 Mon Sep 17 00:00:00 2001 From: Glen Date: Thu, 5 Sep 2024 16:07:37 +0200 Subject: [PATCH] Added documentation directory for StrawberryShake v14 (#7435) --- website/src/docs/docs.json | 100 +++++ .../strawberryshake/v14/caching/entities.md | 5 + .../docs/strawberryshake/v14/caching/index.md | 67 +++ .../v14/caching/invalidation.md | 5 + .../docs/strawberryshake/v14/configuration.md | 34 ++ .../v14/get-started/console.md | 189 +++++++++ .../strawberryshake/v14/get-started/index.md | 243 +++++++++++ .../v14/get-started/xamarin.md | 396 ++++++++++++++++++ website/src/docs/strawberryshake/v14/index.md | 15 + .../v14/migrating/migrate-from-12-to-13.md | 70 ++++ .../v14/networking/authentication.md | 156 +++++++ .../strawberryshake/v14/networking/index.md | 61 +++ .../strawberryshake/v14/performance/index.md | 34 ++ .../v14/performance/persisted-queries.md | 96 +++++ .../v14/performance/persisted-state.md | 7 + .../src/docs/strawberryshake/v14/scalars.md | 203 +++++++++ .../docs/strawberryshake/v14/subscriptions.md | 55 +++ .../src/docs/strawberryshake/v14/tooling.md | 66 +++ 18 files changed, 1802 insertions(+) create mode 100644 website/src/docs/strawberryshake/v14/caching/entities.md create mode 100644 website/src/docs/strawberryshake/v14/caching/index.md create mode 100644 website/src/docs/strawberryshake/v14/caching/invalidation.md create mode 100644 website/src/docs/strawberryshake/v14/configuration.md create mode 100644 website/src/docs/strawberryshake/v14/get-started/console.md create mode 100644 website/src/docs/strawberryshake/v14/get-started/index.md create mode 100644 website/src/docs/strawberryshake/v14/get-started/xamarin.md create mode 100644 website/src/docs/strawberryshake/v14/index.md create mode 100644 website/src/docs/strawberryshake/v14/migrating/migrate-from-12-to-13.md create mode 100644 website/src/docs/strawberryshake/v14/networking/authentication.md create mode 100644 website/src/docs/strawberryshake/v14/networking/index.md create mode 100644 website/src/docs/strawberryshake/v14/performance/index.md create mode 100644 website/src/docs/strawberryshake/v14/performance/persisted-queries.md create mode 100644 website/src/docs/strawberryshake/v14/performance/persisted-state.md create mode 100644 website/src/docs/strawberryshake/v14/scalars.md create mode 100644 website/src/docs/strawberryshake/v14/subscriptions.md create mode 100644 website/src/docs/strawberryshake/v14/tooling.md diff --git a/website/src/docs/docs.json b/website/src/docs/docs.json index 5811b2d3b5a..065cb078cff 100644 --- a/website/src/docs/docs.json +++ b/website/src/docs/docs.json @@ -1608,6 +1608,106 @@ "metaDescription": "Strawberry Shake is an incredible GraphQL client for the .NET ecosystem, that helps developers to build awesome UIs in Blazor, Maui, and more.", "latestStableVersion": "v13", "versions": [ + { + "path": "v14", + "title": "v14", + "items": [ + { + "path": "index", + "title": "Introduction" + }, + { + "path": "get-started", + "title": "Get Started", + "items": [ + { + "path": "index", + "title": "Blazor" + }, + { + "path": "xamarin", + "title": "Xamarin" + }, + { + "path": "console", + "title": "Console" + } + ] + }, + { + "path": "subscriptions", + "title": "Subscriptions" + }, + { + "path": "tooling", + "title": "Tooling / CLI" + }, + { + "path": "caching", + "title": "Caching", + "items": [ + { + "path": "index", + "title": "Overview" + }, + { + "path": "entities", + "title": "Entities" + }, + { + "path": "invalidation", + "title": "Invalidation" + } + ] + }, + { + "path": "performance", + "title": "Performance", + "items": [ + { + "path": "index", + "title": "Overview" + }, + { + "path": "persisted-queries", + "title": "Persisted Queries" + }, + { + "path": "persisted-state", + "title": "Persisted State" + } + ] + }, + { + "path": "networking", + "title": "Networking", + "items": [ + { + "path": "index", + "title": "Protocols" + }, + { + "path": "authentication", + "title": "Authentication" + } + ] + }, + { + "path": "scalars", + "title": "Scalars" + }, + { + "path": "migrating", + "title": "Migrating", + "items": [ + { + "path": "migrate-from-12-to-13", + "title": "Migrate from 12 to 13" + } + ] + } + ] + }, { "path": "v13", "title": "v13", diff --git a/website/src/docs/strawberryshake/v14/caching/entities.md b/website/src/docs/strawberryshake/v14/caching/entities.md new file mode 100644 index 00000000000..0803c0d65c2 --- /dev/null +++ b/website/src/docs/strawberryshake/v14/caching/entities.md @@ -0,0 +1,5 @@ +--- +title: "Entities" +--- + +> We are still working on the documentation for Strawberry Shake so help us by finding typos, missing things or write some additional docs with us. diff --git a/website/src/docs/strawberryshake/v14/caching/index.md b/website/src/docs/strawberryshake/v14/caching/index.md new file mode 100644 index 00000000000..eec3f9173b6 --- /dev/null +++ b/website/src/docs/strawberryshake/v14/caching/index.md @@ -0,0 +1,67 @@ +--- +title: "Caching" +--- + +> We are still working on the documentation for Strawberry Shake, so help us by finding typos, missing things, or write some additional docs with us. + +StrawberryShake stores the result of GraphQL requests in a normalized entity store. The entity store allows your client to execute GraphQL requests with various strategies to reduce the need for network requests. Moreover, the normalized entities are updated by every request the client does, which means that you can build fully reactive components that change as the state in the store changes. + +```mermaid +sequenceDiagram + participant Generated Client + participant Operation Store + participant Entity Store + participant GraphQL Server + Generated Client->>Operation Store: Queries local store + Operation Store->>GraphQL Server: Queries GraphQL server + Note over Entity Store: Normalize response into entities + GraphQL Server->>Entity Store: Returns GraphQL response + Note over Operation Store: Builds operation result from entities + Entity Store->>Operation Store: Returns entities for operation + Operation Store->>Generated Client: Returns operation result +``` + +# Strategies + +We support three basic strategies to interact with the store and fetch data. + +## Network Only + +Network only is the simplest strategy and will fetch from the network and only then update the store. This means that our initial call will always get fresh data and at the same time update other request results watching the same entities. + +If we use the reactive APIs in combination with network only we will still get updates whenever other requests fetch data for the entities we are watching. + +## Cache First + +Cache first is essentially the opposite of network only since it will first fetch from the store, and if the store has the data needed, it will not make any network requests. If the store does not have the data needed, it will go to the network and try to get the data and update the store. + +## Cache and Network + +The last strategy is a combination of the first two. The client will first try to get the data from the store. This gives us fast data response time if the store already has the data. After that the store will update that data for this request with data from the network which in consequence will trigger our subscription and serve us new data. + +## Configuration + +The global strategy default can be set on our dependency injection setup method. + +```csharp +builder.Services + .AddConferenceClient(ExecutionStrategy.CacheFirst) // <---- + .ConfigureHttpClient(client => client.BaseAddress = new Uri("http://localhost:5050/graphql")) + .ConfigureWebSocketClient(client => client.Uri = new Uri("ws://localhost:5050/graphql")); +``` + +The global strategy default can then be overwritten by any `Watch` method for a particular request. + +```csharp +storeSession = + ConferenceClient + .GetSessions + .Watch(ExecutionStrategy.CacheFirst) // <---- + .Where(t => !t.Errors.Any()) + .Select(t => t.Data!.Sessions!.Nodes) + .Subscribe(result => + { + sessions = result; + StateHasChanged(); + }); +``` diff --git a/website/src/docs/strawberryshake/v14/caching/invalidation.md b/website/src/docs/strawberryshake/v14/caching/invalidation.md new file mode 100644 index 00000000000..3a6339c72f3 --- /dev/null +++ b/website/src/docs/strawberryshake/v14/caching/invalidation.md @@ -0,0 +1,5 @@ +--- +title: "Invalidation" +--- + +> We are still working on the documentation for Strawberry Shake so help us by finding typos, missing things or write some additional docs with us. diff --git a/website/src/docs/strawberryshake/v14/configuration.md b/website/src/docs/strawberryshake/v14/configuration.md new file mode 100644 index 00000000000..4674d2b6ee3 --- /dev/null +++ b/website/src/docs/strawberryshake/v14/configuration.md @@ -0,0 +1,34 @@ +--- +title: Configuration +--- + +Strawberry Shake is configured by altering the `.graphqlrc.json` at the root of your project. +All settings to into `extensions.strawberryShake` object. +Here is a full configuration with all possibilities: + +```json +{ + // The path of the schema file, that will be used to generate the client. + // This setting may also be used by other tooling, because it is a default field of graphql-spec + "schema": "schema.graphql", + // The selector that determines, what files will be regarded as graphql documents + // This setting may also be used by other tooling, because it is a default field of graphql-spec + "documents": "**/*.graphql", + "extensions": { + // Here do only Strawberry Shake specific settings live + "strawberryShake": { + // The name of the generated client + "name": "ChatClient", + // The namespace of all the generated files of the client + "namespace": "Demo", + // The URL of the GraphQL api you want to consume with the client + "url": "https://workshop.chillicream.com/graphql/", + // The access level modifier of the generated client + "accessModifier": "public", + // Shall your client be based on dependency injection? If yes, all needed setup code + // will be generated for you, so that you only have to add the client to your DI container. + "dependencyInjection": true + } + } +} +``` diff --git a/website/src/docs/strawberryshake/v14/get-started/console.md b/website/src/docs/strawberryshake/v14/get-started/console.md new file mode 100644 index 00000000000..a80114dd4ff --- /dev/null +++ b/website/src/docs/strawberryshake/v14/get-started/console.md @@ -0,0 +1,189 @@ +--- +title: "Get started with Strawberry Shake in a Console application" +--- + +In this tutorial we will walk you through the basics of adding a Strawberry Shake GraphQL client to a console project. For this example we will create a simple console application and fetch some simple data from our demo backend. + +Strawberry Shake is not limited to console application and can be used with any .NET standard compliant library. + +In this tutorial, we will teach you: + +- How to add the Strawberry Shake CLI tools. +- How to generate source code from .graphql files, that contain operations. +- How to use the generated client in a classical or reactive way. +- How to disable state management for ASP.NET core use-cases. + +## Step 1: Add the Strawberry Shake CLI tools + +The Strawberry Shake tool will help you to set up your project to create a GraphQL client. + +Open your preferred terminal and select a directory where you want to add the code of this tutorial. + +1. Create a dotnet tool-manifest. + +```bash +dotnet new tool-manifest +``` + +2. Install the Strawberry Shake tools. + +```bash +dotnet tool install StrawberryShake.Tools --local +``` + +## Step 2: Create a console project + +Next, we will create our console project so that we have a little playground. + +1. First, a new solution called `Demo.sln`. + +```bash +dotnet new sln -n Demo +``` + +2. Create a new console application. + +```bash +dotnet new console -n Demo +``` + +3. Add the project to the solution `Demo.sln`. + +```bash +dotnet sln add ./Demo +``` + +## Step 3: Install the required packages + +Strawberry Shake supports multiple GraphQL transport protocols. In this example we will use the standard GraphQL over HTTP protocol to interact with our GraphQL server. + +1. Add the `StrawberryShake.Server` package to your project in order to add our code generation. + +```bash +dotnet add Demo package StrawberryShake.Server +``` + +## Step 4: Add a GraphQL client to your project using the CLI tools + +To add a client to your project, you need to run `dotnet graphql init {{ServerUrl}} -n {{ClientName}}`. + +In this tutorial we will use our GraphQL workshop to create a list of sessions that we will add to our console application. + +> If you want to have a look at our GraphQL workshop head over [here](https://github.com/ChilliCream/graphql-workshop). + +1. Add the conference client to your console application. + +```bash +dotnet graphql init https://workshop.chillicream.com/graphql/ -n ConferenceClient -p ./Demo +``` + +2. Customize the namespace of the generated client to be `Demo.GraphQL`. For this head over to the `.graphqlrc.json` and insert a namespace property to the `StrawberryShake` section. + +```json +{ + "schema": "schema.graphql", + "documents": "**/*.graphql", + "extensions": { + "strawberryShake": { + "name": "ConferenceClient", + "namespace": "Demo.GraphQL", + "url": "https://workshop.chillicream.com/graphql/", + "dependencyInjection": true + } + } +} +``` + +Now that everything is in place let us write our first query to ask for a list of session titles of the conference API. + +3. Choose your favorite IDE and the solution. If your are using VSCode do the following: + +```bash +code ./Demo +``` + +4. Create new query document `GetSessions.graphql` with the following content: + +```graphql +query GetSessions { + sessions(order: { title: ASC }) { + nodes { + title + } + } +} +``` + +5. Compile your project. + +```bash +dotnet build +``` + +With the project compiled, you should now see in the directory `./obj///berry` the generated code that your applications can leverage. For example, if you've run a Debug build for .NET 8, the path would be `./obj/Debug/net8.0/berry`. + +![Visual Studio code showing the generated directory.](../../../shared/berry_console_generated.png) + +1. Head over to the `Program.cs` and add the new `ConferenceClient` to the dependency injection. + +> In some IDEs it is still necessary to reload the project after the code was generated to update the IntelliSense. So, if you have any issues in the next step with IntelliSense just reload the project and everything should be fine. + +```csharp +using System; +using Microsoft.Extensions.DependencyInjection; +using Demo.GraphQL; + +namespace Demo +{ + class Program + { + static void Main(string[] args) + { + var serviceCollection = new ServiceCollection(); + + serviceCollection + .AddConferenceClient() + .ConfigureHttpClient(client => client.BaseAddress = new Uri("https://workshop.chillicream.com/graphql")); + + IServiceProvider services = serviceCollection.BuildServiceProvider(); + + IConferenceClient client = services.GetRequiredService(); + } + } +} +``` + +## Step 5: Use the ConferenceClient to perform a simple fetch + +In this section we will perform a simple fetch with our `ConferenceClient` and output the result to the console. + +1. Head over to `Program.cs`. + +2. Add the following code to your main method to execute the `GetSessions` query. + +```csharp +static async Task Main(string[] args) +{ + var serviceCollection = new ServiceCollection(); + + serviceCollection + .AddConferenceClient() + .ConfigureHttpClient(client => client.BaseAddress = new Uri("https://workshop.chillicream.com/graphql")); + + IServiceProvider services = serviceCollection.BuildServiceProvider(); + + IConferenceClient client = services.GetRequiredService(); + + var result = await client.GetSessions.ExecuteAsync(); + result.EnsureNoErrors(); + + foreach (var session in result.Data.Sessions.Nodes) + { + Console.WriteLine(session.Title); + } +} +``` + +3. Start the console application with `dotnet run --project ./Demo` and see if your code works. + +![Started console application that shows a list of sessions](../../../shared/berry_console_session_list.png) diff --git a/website/src/docs/strawberryshake/v14/get-started/index.md b/website/src/docs/strawberryshake/v14/get-started/index.md new file mode 100644 index 00000000000..1a64dd3d2e7 --- /dev/null +++ b/website/src/docs/strawberryshake/v14/get-started/index.md @@ -0,0 +1,243 @@ +--- +title: "Get started with Strawberry Shake and Blazor" +--- + +In this tutorial we will walk you through the basics of adding a Strawberry Shake GraphQL client to a Blazor for WebAssembly project. For this example we will create a Blazor for WebAssembly application and fetch some simple data from our demo backend. + +