What are Aspire integrations?

Aspire integrations are AppHost packages that add APIs for defining resources your app depends on, such as databases, caches, messaging systems, and cloud services.

Integrations tell Aspire how to create, connect to, and pass connection details for resources in your app model. An integration can start a local resource, create or connect to a cloud resource, or point to an existing service such as a local SQL server.

In the AppHost, integrations add methods to IDistributedApplicationBuilder so you can describe those resources in the app model. Key characteristics include:

• Tagged with aspire, integration, and hosting in official packages
• Available from both official Aspire releases and community contributions through the Community Toolkit
• Define resources for different services and platforms
• Pass connection information to apps that reference those resources

After you create resources in the AppHost, you can pass them to apps such as APIs or web front ends by calling the “with reference” APIs. A reference tells Aspire that an app depends on a resource. When Aspire starts, it gives the app the connection details it needs by setting environment variables.

The environment variables Aspire sets depend on the type of resource being referenced. For example:

• Connection string resources: Aspire sets a ConnectionStrings__{name} environment variable, where {name} matches the resource name. For example, referencing a resource named "cache" injects ConnectionStrings__cache=localhost:54321, where the value is the connection string.
• Service endpoint resources: Aspire sets {NAME}_{SCHEME} variables for app endpoints. For example, referencing a project named apiservice, that is available on port 7001, sets APISERVICE_HTTPS=https://localhost:7001.

Other environment variables often include credentials, port numbers, and other connection details.

Any application can read these environment variables to connect to its dependencies directly, without any Aspire-specific libraries.

Not every integration provides every capability. Each package supports the capabilities that make sense for the resource it models. Depending on the package, an integration can:

• Define resources: Add containers, cloud resources, executable resources, or references to existing infrastructure to the AppHost model.
• Share connection information: Pass endpoints, connection strings, credentials, and other resource details to consuming apps through references.
• Support local development: Run common dependencies locally and view their state in the Aspire Dashboard.
• Support deployment: Keep resource relationships in the app model so deployment tooling can understand how apps and resources connect.

Aspire integrations are updated each release to use current stable versions of the resources they depend on. For example, when a container image has a new version, the related integration can update to use it. The Aspire update type (major, minor, patch) doesn’t necessarily match the update type of the underlying resource. For example, an Aspire patch release might include a major update to a container image when necessary.

When a resource has a major breaking change, Aspire may temporarily provide version-specific integration packages to make upgrades easier.