Skip to content

Commit ac835b2

Browse files
glen-84glen-84
authored
Added v16 documentation (#8275)
1 parent 819f23c commit ac835b2

File tree

101 files changed

+24023
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

101 files changed

+24023
-0
lines changed

‎website/src/docs/docs.json

Lines changed: 482 additions & 0 deletions
Large diffs are not rendered by default.

‎website/src/docs/fusion/v16/aspire.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: "Integrating Fusion with Aspire"
3+
---
4+
5+
# Introduction
6+
7+
<Video videoId="AHitpPCeM00" />
8+
9+
Integrating Fusion with [Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview) enhances your development workflow by automating the composition of your gateway and subgraphs during the build process.
10+
Aspire acts as an internal orchestrator, streamlining the setup and management of distributed systems and microservices.
11+
By configuring your AppHost to compose all referenced source systems on build, any changes made to downstream services are immediately reflected, ensuring you always have the latest composed version running in development.
12+
13+
# Overview of Aspire
14+
15+
[Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview) is an internal orchestrator designed to streamline your development experience when working with distributed systems and microservices.
16+
17+
It offers:
18+
19+
- [**Service Defaults**](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/service-defaults): Extension methods that add essential configurations to your services, such as telemetry, health endpoints, and service discovery.
20+
- [**AppHost**](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/app-host-overview?tabs=docker): An orchestrator that defines dependencies between your applications and automates the resolution and startup of these dependencies.
21+
22+
By integrating Aspire with Fusion, you can:
23+
24+
- Automatically compose your Fusion gateway with all referenced subgraphs on build.
25+
- Simplify the configuration and management of your federated GraphQL services.
26+
- Enhance your debugging experience with built-in telemetry and logging.
27+
28+
# Setting Up the AppHost with Fusion and Aspire
29+
30+
To integrate Fusion with Aspire, you need to configure your AppHost to include your gateway and subgraphs.
31+
The AppHost serves as the central orchestrator, managing dependencies and automating the composition process during the build.
32+
33+
Below is an example of how to set up your AppHost:
34+
35+
```csharp
36+
var builder = DistributedApplication.CreateBuilder(args);
37+
38+
var ordering = builder.AddProject<Projects.quick_start_Ordering>("ordering");
39+
var products = builder.AddProject<Projects.quick_start_Products>("products");
40+
41+
builder
42+
.AddFusionGateway<Projects.quick_start_Gateway>("gateway")
43+
.WithSubgraph(ordering)
44+
.WithSubgraph(products);
45+
46+
// Important: Use 'Compose' before 'Run' to enable build-time composition
47+
builder.Build().Compose().Run();
48+
```
49+
50+
In this configuration:
51+
52+
- **Create the Builder**: Initialize a new distributed application builder with `DistributedApplication.CreateBuilder(args)`.
53+
- **Add Subgraph Projects**: Include your subgraph projects (e.g., `ordering` and `products`) using `builder.AddProject<TProject>("name")`. These represent your downstream services or subgraphs.
54+
- **Configure the Fusion Gateway**: Add your Fusion gateway project with `builder.AddFusionGateway<TProject>("name")` and associate the subgraphs using `.WithSubgraph(subgraph)`.
55+
- **Compose and Run**: Use `builder.Build().Compose().Run();` instead of the usual `builder.Build().Run();`. The `.Compose()` method triggers the composition of your federated schema during the build process.
56+
57+
By including `.Compose()`, Aspire automatically composes the gateway every time you build the application. This ensures that any changes made to your subgraphs are incorporated into the Fusion gateway without manual intervention, providing an up-to-date composed schema whenever you run your application.
58+
59+
# Options
60+
61+
You can further customize the composition process by using the `WithOptions` to configure specific settings for your gateway.
62+
63+
```csharp
64+
services
65+
.AddGraphQLServer()
66+
.AddFusion()
67+
.WithOptions(new FusionCompositionOptions
68+
{
69+
// equivalent to `--enable-nodes` CLI option
70+
EnableGlobalObjectIdentification = true
71+
});
72+
```
73+
74+
# Example Repository
75+
76+
A practical example demonstrating this integration is available in the [HotChocolate Examples Repository](https://github.com/ChilliCream/hotchocolate-examples/tree/master/fusion/aspire) under the `fusion/aspire` directory. This repository illustrates:
77+
78+
- Setting up the AppHost with multiple subgraphs and a Fusion gateway.
79+
- Configuring service defaults and endpoints.
80+
- Running the application to see the composed schema in action.
81+
82+
By exploring this example, you can gain a deeper understanding of how to implement the integration in your own projects.

‎website/src/docs/fusion/v16/cli.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: "Fusion CLI Documentation"
3+
---
4+
5+
The Fusion Command Line Interface is a tool designed to assist the development and management of APIs using Fusion. This documentation provides a comprehensive guide to the Fusion CLI, covering installation, commands, options, and usage examples to help you effectively utilize the tool in your projects.
6+
7+
## Introduction
8+
9+
Fusion CLI is a command-line tool that assists developers in composing, packaging, and managing federated schemas for Fusion gateways.
10+
11+
## Installation
12+
13+
To install the Fusion CLI, ensure you have the .NET SDK installed on your machine. Then, install the CLI globally using the .NET tool command:
14+
15+
```bash
16+
dotnet tool install -g HotChocolate.Fusion.CommandLine
17+
```
18+
19+
This command installs the Fusion CLI globally, making it accessible from any directory in your command line.
20+
21+
## Commands
22+
23+
### `fusion compose`
24+
25+
The `compose` command is used to create or update a Fusion gateway package (`.fgp` file) by composing multiple APIs packages (`.fsp` files). This package is then used by the Fusion gateway to serve a unified schema.
26+
27+
**Description:**
28+
29+
Composes multiple APIs into a Fusion gateway package.
30+
31+
**Usage:**
32+
33+
```bash
34+
fusion compose [options]
35+
```
36+
37+
**Options:**
38+
39+
- `-p`, `--package`, `--package-file <package-file>` (REQUIRED): Specifies the path to the Fusion gateway package file (`gateway.fgp`). This file will be created or updated by the compose command.
40+
- `-s`, `--subgraph`, `--subgraph-package-file <subgraph-package-file>`: Specifies the path to a subgraph package file (`.fsp`) to include in the composition. This option can be used multiple times to add multiple subgraphs.
41+
- `--package-settings`, `--package-settings-file`, `--settings <package-settings-file>`: Specifies the path to a Fusion package settings file (`fusion-subgraph.json`). This file contains additional settings for the composition.
42+
- `-w`, `--working-directory <working-directory>`: Sets the working directory for the command. Defaults to the current executing directory.
43+
- `--enable-nodes`: Enables the Node interface feature in the gateway, allowing it to understand `node(id: ...)` queries.
44+
- `-r`, `--remove <subgraph-name>`: Removes a specified subgraph from the existing composition in the gateway package.
45+
- `-?`, `-h`, `--help`: Shows help and usage information for the command.
46+
47+
---
48+
49+
### `fusion subgraph`
50+
51+
The `subgraph` command group contains commands related to subgraph management, such as packaging subgraphs for composition.
52+
53+
#### `fusion subgraph pack`
54+
55+
The `pack` command creates a Fusion subgraph package (`.fsp` file) from a subgraph's schema and configuration. This package is then used in the composition process.
56+
57+
**Description:**
58+
59+
Creates a Fusion subgraph package from a subgraph's schema and configuration files.
60+
61+
**Usage:**
62+
63+
```bash
64+
fusion subgraph pack [options]
65+
```
66+
67+
**Options:**
68+
69+
- `-p`, `--package`, `--package-file <package-file>`: Specifies the output path for the subgraph package file (`YourService.fsp`). Defaults to `<SourceName>.fsp` if not specified.
70+
- `-s`, `--schema`, `--schema-file <schema-file>`: Specifies the path to the subgraph's schema file (`schema.graphql`).
71+
- `-c`, `--config`, `--config-file <config-file>`: Specifies the path to the subgraph's configuration file (`subgraph-config.json`).
72+
- `-e`, `--extension`, `--extension-file <extension-file>`: Specifies paths to any schema extension files to include. This option can be used multiple times for multiple files.
73+
- `-w`, `--working-directory <working-directory>`: Sets the working directory for the command. Defaults to the current executing directory.
74+
- `-?`, `-h`, `--help`: Shows help and usage information for the command.
75+
76+
## Examples
77+
78+
This section provides practical examples of using the Fusion CLI commands in common scenarios.
79+
80+
### Example 1: Packing a Downstream Service
81+
82+
Suppose you have a subgraph named `Products` with a schema file `schema.graphql` and a configuration file `subgraph-config.json`. To create a subgraph package, navigate to the subgraph's directory and run:
83+
84+
```bash
85+
fusion subgraph pack
86+
```
87+
88+
In case your schema and configuration files have different names or are located in a different directory, you can specify them using the `-s` and `-c` options:
89+
90+
```bash
91+
fusion subgraph pack -s other-schema.graphql -c config.json
92+
```
93+
94+
This command generates a `Products.fsp` package file in the current directory.
95+
96+
### Example 2: Composing a Gateway Package
97+
98+
To compose a Fusion gateway package from multiple subgraph packages, use the `compose` command. For example, to compose the `Products` and `Orders` subgraphs into a gateway package named `gateway.fgp`, run:
99+
100+
```bash
101+
fusion compose -p gateway.fgp -s ../Products/Products.fsp -s ../Orders/Orders.fsp
102+
```
103+
104+
This command creates or updates the `gateway.fgp` file with the composed schema from both subgraphs.
105+
106+
### Example 3: Removing a Downstream Service from the Composition
107+
108+
If you need to remove the `Orders` subgraph from an existing gateway package, use the `--remove` option:
109+
110+
```bash
111+
fusion compose -p gateway.fgp -r Orders
112+
```
113+
114+
This command updates `gateway.fgp`, removing the `Orders` subgraph from the composition.
115+
116+
### Example 4: Enabling Node Interface Support
117+
118+
To enable the Node interface feature in your gateway, allowing it to handle `node` queries, include the `--enable-nodes` flag during composition:
119+
120+
```bash
121+
fusion compose -p gateway.fgp -s ../Products/Products.fsp --enable-nodes
122+
```
123+
124+
### Example 5: Specifying Working Directory
125+
126+
If your schema and configuration files are located in a different directory, you can specify the working directory using `-w`:
127+
128+
```bash
129+
fusion subgraph pack -s schema.graphql -c subgraph-config.json -w /path/to/subgraph
130+
```
131+
132+
## Additional Resources
133+
134+
- **Fusion Documentation:** Explore the [official Fusion documentation](/docs/fusion/v14) for in-depth guides and references.
135+
- **Fusion Quick Start Guide:** Get started with Fusion by following the [Quick Start Guide](/docs/fusion/v16/quick-start).
136+
- **ChilliCream Community:** Join the [ChilliCream community](https://slack.chillicream.com) to ask questions, share experiences, and contribute to the project.

0 commit comments

Comments
 (0)