Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/integration_proposal.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ body:
validations:
required: false
attributes:
label: .NET Aspire issue link
description: If this was discussed in the .NET Aspire repository, please provide a link to the issue/discussion.
label: Aspire issue link
description: If this was discussed in the Aspire repository, please provide a link to the issue/discussion.
- type: textarea
id: description
validations:
Expand Down
8 changes: 4 additions & 4 deletions .github/chatmodes/New Aspire Hosting integration.chatmode.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
description: "This chat mode is to create a new .NET Aspire hosting integration, using the design in the Community Toolkit repo."
description: "This chat mode is to create a new Aspire hosting integration, using the design in the Community Toolkit repo."
tools: [
"changes",
"codebase",
Expand All @@ -17,7 +17,7 @@ tools: [

# New Aspire Hosting Integration

You are going to develop a new .NET Aspire hosting integration. The following in the process in which you need to go through to complete the task.
You are going to develop a new Aspire hosting integration. The following in the process in which you need to go through to complete the task.

## 1. Collect Requirements

Expand Down Expand Up @@ -207,9 +207,9 @@ The extension method should meet the following requirements:

## 4. Sample Usage

You need to create a sample usage of the hosting integration in the `examples` folder. This should be a minimal example that demonstrates how to use the hosting integration in a .NET Aspire application.
You need to create a sample usage of the hosting integration in the `examples` folder. This should be a minimal example that demonstrates how to use the hosting integration in an Aspire application.

Start by scaffolding a new .NET Aspire App Host project in the `examples` folder. This can be done using the following command:
Start by scaffolding a new Aspire App Host project in the `examples` folder. This can be done using the following command:

```bash
dotnet new aspire-apphost -n CommunityToolkit.Aspire.Hosting.<HostingIntegrationName>.AppHost -o examples/CommunityToolkit.Aspire.Hosting.<HostingIntegrationName>.AppHost
Expand Down
2 changes: 1 addition & 1 deletion .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

### Project Overview

- This repo is a collection of community-driven integrations and extensions for [.NET Aspire](https://aka.ms/dotnet/aspire), supporting a wide range of runtimes and cloud-native patterns.
- This repo is a collection of community-driven integrations and extensions for [Aspire](https://aka.ms/dotnet/aspire), supporting a wide range of runtimes and cloud-native patterns.
- Major components are organized by integration in `src/`, with tests in `tests/` and usage examples in `examples/`.
- Each integration is a NuGet package, following naming: `CommunityToolkit.Aspire.Hosting.*` (hosting) or `CommunityToolkit.Aspire.*` (client).

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ This repository contains the source code for the Aspire Community Toolkit, a col
| Package | Description |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - **Learn More**: [`Hosting.Golang`][golang-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.Hosting.Golang][golang-shields]][golang-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.Golang][golang-shields-preview]][golang-nuget-preview] | A hosting integration Golang apps. |
| - **Learn More**: [`Hosting.Java`][java-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.Hosting.Java][java-shields]][java-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.Java][java-shields-preview]][java-nuget-preview] | An integration for running Java code in .NET Aspire either using the local JDK or using a container. |
| - **Learn More**: [`Hosting.Java`][java-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.Hosting.Java][java-shields]][java-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.Java][java-shields-preview]][java-nuget-preview] | An integration for running Java code in Aspire either using the local JDK or using a container. |
| - **Learn More**: [`Hosting.NodeJS.Extensions`][nodejs-ext-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.NodeJS.Extensions][nodejs-ext-shields]][nodejs-ext-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.JavaScript.Extensions][nodejs-ext-shields-preview]][nodejs-ext-nuget-preview] | An integration that contains some additional extensions for running Node.js applications |
| - **Learn More**: [`Hosting.Ollama`][ollama-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.Hosting.Ollama][ollama-shields]][ollama-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.Ollama][ollama-shields-preview]][ollama-nuget-preview] | An Aspire hosting integration leveraging the [Ollama](https://ollama.com) container with support for downloading a model on startup. |
| - **Learn More**: [`OllamaSharp`][ollama-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.OllamaSharp][ollamasharp-shields]][ollamasharp-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.OllamaSharp][ollamasharp-shields-preview]][ollamasharp-nuget-preview] | An Aspire client integration for the [OllamaSharp](https://github.com/awaescher/OllamaSharp) package. |
Expand Down
12 changes: 6 additions & 6 deletions docs/create-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

So, you want to create a new integration for the Aspire Community Toolkit? That's awesome! This guide will walk you through the process of creating a new integration.

First up, make sure you've had a read of the [Contributing guide](../CONTRIBUTING.md) to understand the contribution guidelines, and then familiarise yourself with creating a custom .NET Aspire integration for [hosting](https://learn.microsoft.com/dotnet/aspire/extensibility/custom-hosting-integration?tabs=windows) or for [clients](https://learn.microsoft.com/dotnet/aspire/extensibility/custom-client-integration).
First up, make sure you've had a read of the [Contributing guide](../CONTRIBUTING.md) to understand the contribution guidelines, and then familiarise yourself with creating a custom Aspire integration for [hosting](https://aspire.dev/integrations/custom-integrations/hosting-integrations/) or for [clients](https://aspire.dev/integrations/custom-integrations/client-integrations/).

## 📂 Repository Structure

Expand All @@ -18,7 +18,7 @@ Be sure to read through the [Setting up your Development Environment](./setup.md

## 🚀 Getting Started

To create a new integration, you'll need to create a new project in the `src/` directory. The project needs to be prefixed with `CommunityToolkit.Aspire.` and should be named after the integration you're creating, using the naming guidelines from the .NET Aspire team. For example, if you're creating a **Hosting** integration, then the project name should be `CommunityToolkit.Aspire.Hosting.MyIntegration`, whereas if you're creating a **Client** integration, then the project name should be `CommunityToolkit.Aspire.MyIntegration`.
To create a new integration, you'll need to create a new project in the `src/` directory. The project needs to be prefixed with `CommunityToolkit.Aspire.` and should be named after the integration you're creating, using the naming guidelines from the Aspire team. For example, if you're creating a **Hosting** integration, then the project name should be `CommunityToolkit.Aspire.Hosting.MyIntegration`, whereas if you're creating a **Client** integration, then the project name should be `CommunityToolkit.Aspire.MyIntegration`.

> Note: All integration packages will have the `Aspire.Hosting` NuGet package added as a dependency, as well as some standard MSBuild properties. You can see what is pre-configured in the `Directory.Build.props` file.

Expand Down Expand Up @@ -95,7 +95,7 @@ GitHub Actions Windows runners do not support Linux container images, so if your

#### Waiting for the resource to start

If the resource your integration exposes does not integrate into the .NET Aspire health check model, you may need to parse its logs to determine when it is ready to accept requests. To do this, use the `WaitForTextAsync` extension method on the `DistributionApplication` object to wait for a specific message to appear in the logs. Do note that this method is marked with `CTASPIRE001` so you will need to disable that warning where you use it. You can learn more about `CTASPIRE001` in the [Diagnostics documentation](./diagnostics.md).
If the resource your integration exposes does not integrate into the Aspire health check model, you may need to parse its logs to determine when it is ready to accept requests. To do this, use the `WaitForTextAsync` extension method on the `DistributionApplication` object to wait for a specific message to appear in the logs. Do note that this method is marked with `CTASPIRE001` so you will need to disable that warning where you use it. You can learn more about `CTASPIRE001` in the [Diagnostics documentation](./diagnostics.md).

### Adding Tests to the CI pipeline

Expand All @@ -107,7 +107,7 @@ The easiest way to update that list is to run the `./eng/testing/generate-test-l

You'll need to add a `README.md` file to the folder your integration is created in, this will be used in the NuGet package that is generated. This should be a high level overview of the integration and does not need to be a complete doc set.

For the complete docs, you'll need to create a PR to the [`microsoft/aspire.dev`](https://github.com/microsoft/aspire.dev) repository. This will be reviewed by the docs owners and merged into the main docs for .NET Aspire. The aspire.dev repository has an agent that can scaffold out a docs page from the README to help speed up your work.
For the complete docs, you'll need to create a PR to the [`microsoft/aspire.dev`](https://github.com/microsoft/aspire.dev) repository. This will be reviewed by the docs owners and merged into the main docs for Aspire. The aspire.dev repository has an agent that can scaffold out a docs page from the README to help speed up your work.

Lastly, update the `README.md` in the root of this repository to include your new integration in the table of integrations.

Expand All @@ -120,13 +120,13 @@ Your integration will be automatically packaged as a NuGet package when a PR is
Most of the NuGet metadata will be automatically added to the generated nuspec file during the packaging process in the CI pipeline but there are two pieces of metadata that you will need to add manually to the csproj file for your integration:

- `Description` - A short description of the integration.
- `AdditionalTags` - A space-separated list of tags that describe the integration (some tags are added by default, such as `aspire`, use this to add more specific tags for your integration). Ensure to add the integration type (`client` or `hosting`) as a tag so the integration can be easily discovered in the Visual Studio tooling for .NET Aspire.
- `AdditionalTags` - A space-separated list of tags that describe the integration (some tags are added by default, such as `aspire`, use this to add more specific tags for your integration). Ensure to add the integration type (`client` or `hosting`) as a tag so the integration can be easily discovered in the Visual Studio tooling for Aspire.

Here's an example from the OllamaSharp integration:

```xml
<PropertyGroup>
<Description>A .NET Aspire client integration for the OllamaSharp library.</Description>
<Description>An Aspire client integration for the OllamaSharp library.</Description>
<AdditionalPackageTags>ollama ai ollamasharp</AdditionalPackageTags>
</PropertyGroup>
```
Expand Down
6 changes: 3 additions & 3 deletions docs/diagnostics.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ Some of the API's in the Aspire Community Toolkit are decorated with the [`Exper

## CTASPIRE001

There are cases where there is an API provided by the Aspire Community Toolkit that is an intermidiary solution until a feature is added to .NET Aspire itself. This could be a private API that is not yet ready for public consumption, or a workaround waiting for the completion of a feature in .NET Aspire.
There are cases where there is an API provided by the Aspire Community Toolkit that is an intermidiary solution until a feature is added to Aspire itself. This could be a private API that is not yet ready for public consumption, or a workaround waiting for the completion of a feature in Aspire.

In these cases, refer to the `<remarks>` docs section of the API for more information on the feature in .NET Aspire and the issue(s) to track.
In these cases, refer to the `<remarks>` docs section of the API for more information on the feature in Aspire and the issue(s) to track.

Once a release of .NET Aspire with that API is available, the API in the Aspire Community Toolkit will be marked as obsolete and will be removed in a future release.
Once a release of Aspire with that API is available, the API in the Aspire Community Toolkit will be marked as obsolete and will be removed in a future release.

## CTASPIRE002

Expand Down
8 changes: 4 additions & 4 deletions docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@

## What is the purpose of this project?

The goal of the project is to be a centralised home for extensions and integrations for [.NET Aspire](https://aka.ms/dotnet/aspire), helping to provide consistency in the way that integrations are built and maintained, as well as easier discoverability for users.
The goal of the project is to be a centralised home for extensions and integrations for [Aspire](https://aka.ms/dotnet/aspire), helping to provide consistency in the way that integrations are built and maintained, as well as easier discoverability for users.

## How is this project different from the official .NET Aspire project?
## How is this project different from the official Aspire project?

The Aspire Community Toolkit is a community-driven project that is maintained by the community and is not officially supported by the .NET Aspire team. The toolkit is a collection of integrations and extensions that are built on top of the .NET Aspire project.
The Aspire Community Toolkit is a community-driven project that is maintained by the community and is not officially supported by the Aspire team. The toolkit is a collection of integrations and extensions that are built on top of the Aspire project.

## How can I contribute to the project?

Anyone can contribute to the Aspire Community Toolkit and before you get started, be sure to read the [Contributing Guide](../CONTRIBUTING.md) to learn how to contribute to the project.

## Should I propose a new integration here on or the `dotnet/aspire` repo?

If you have an idea for a new integration, you should propose it here on the Aspire Community Toolkit repository, rather than [`dotnet/aspire`](https://github.com/dotnet/aspire), as the official .NET Aspire project is focused on the core functionality of the .NET Aspire project.
If you have an idea for a new integration, you should propose it here on the Aspire Community Toolkit repository, rather than [`dotnet/aspire`](https://github.com/dotnet/aspire), as the official Aspire project is focused on the core functionality of the Aspire project.

If you have previously proposed an integration on the `dotnet/aspire` repository, you can still propose it here, but link to the existing issue on the `dotnet/aspire` repository to provide context.

Expand Down
6 changes: 3 additions & 3 deletions docs/versioning.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Overview

The Aspire Community Toolkit follows the [Semantic Versioning 2.0.0](https://semver.org/) specification and aims to keep in sync with the .NET Aspire version numbers to a minor version level. This means that the major version of the toolkit will be the same as the major version of the .NET Aspire framework.
The Aspire Community Toolkit follows the [Semantic Versioning 2.0.0](https://semver.org/) specification and aims to keep in sync with the Aspire version numbers to a minor version level. This means that the major version of the toolkit will be the same as the major version of the Aspire framework.

Individual Community Toolkit NuGet packages may version at a patch level different to .NET Aspire, but the major and minor versions will be the same. For example, a package with the version 8.2.x will be compatible with .NET Aspire 8.2, and the patch version may be different.
Individual Community Toolkit NuGet packages may version at a patch level different to Aspire, but the major and minor versions will be the same. For example, a package with the version 8.2.x will be compatible with Aspire 8.2, and the patch version may be different.

This means that the introduction of a new integration will not result in a major (or minor) version bump of the toolkit, but it may result in a patch version bump to other packages.

## Release Process

The Aspire Community Toolkit aims to be released in sync with .NET Aspire, but there may be a short lag, depending on bandwidth of the maintainers and complexity of any changes.
The Aspire Community Toolkit aims to be released in sync with Aspire, but there may be a short lag, depending on bandwidth of the maintainers and complexity of any changes.

Releases are automated using GitHub Actions, each release will be tagged in the repository with the version number, and a release will be created on GitHub with the release notes (where possible).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

namespace Microsoft.Extensions.Hosting;

// Adds common .NET Aspire services: service discovery, resilience, health checks, and OpenTelemetry.
// Adds common Aspire services: service discovery, resilience, health checks, and OpenTelemetry.
// This project should be referenced by each service project in your solution.
// To learn more about using this project, see https://aka.ms/dotnet/aspire/service-defaults
public static class Extensions
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

namespace Microsoft.Extensions.Hosting;

// Adds common .NET Aspire services: service discovery, resilience, health checks, and OpenTelemetry.
// Adds common Aspire services: service discovery, resilience, health checks, and OpenTelemetry.
// This project should be referenced by each service project in your solution.
// To learn more about using this project, see https://aka.ms/dotnet/aspire/service-defaults
public static class Extensions
Expand Down
Loading
Loading