Integrations Overview

Aspire integrations are a curated suite of packages that make it easy to connect your cloud-native applications with popular services like Redis and PostgreSQL. Each integration provides essential cloud-native capabilities through automatic setup or standardized configuration.

Tip

Always strive to use the latest version of Aspire integrations to take advantage of the latest features, improvements, and security updates.

Integration responsibilities

Most Aspire integrations are made up of two separate libraries, each with a different responsibility. One type represents resources within the app host project—known as hosting integrations. The other type of integration represents client libraries that connect to the resources modeled by hosting integrations, and they’re known as client integrations.

Hosting integrations

Hosting integrations configure applications by provisioning resources (like containers or cloud resources) or pointing to existing instances (such as a local SQL server). These packages model various services, platforms, or capabilities, including caches, databases, logging, storage, and messaging systems.

Hosting integrations extend the IDistributedApplicationBuilder interface to enable the app host project to express resources within its 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
• Enable resource modeling for various services and platforms

Client integrations

Client integrations wire up client libraries to dependency injection (DI), define configuration schema, and add health checks, resiliency, and telemetry where applicable. Aspire client integration libraries are prefixed with Aspire. and then include the full package name that they integrate with, such as Aspire.StackExchange.Redis.

These packages configure existing client libraries to connect to hosting integrations. Key characteristics include:

• Extend the IHostApplicationBuilder interface for client-consuming projects (web apps, APIs)
• Tagged with aspire, integration, and client in official packages
• Available from both official Aspire releases and community contributions through the Community Toolkit

Relationship between hosting and client integrations

Hosting and client integrations work together but are not coupled and can be used independently. Configuration via environment variables connects client integrations to their corresponding hosting integrations, with the AppHost project managing this connection.

Integration features

When you add a client integration to a project within your Aspire solution, service defaults are automatically applied to that project; meaning the Service Defaults project is referenced and the AddServiceDefaults extension method is called. These defaults are designed to work well in most scenarios and can be customized as needed. The following service defaults are applied:

• Observability and telemetry: Automatically sets up logging, tracing, and metrics configurations:

  • Logging: A technique where code is instrumented to produce logs of interesting events that occurred while the program was running.
  • Tracing: A specialized form of logging that helps you localize failures and performance issues within applications distributed across multiple machines or processes.
  • Metrics: Numerical measurements recorded over time to monitor application performance and health. Metrics are often used to generate alerts when potential problems are detected.

• Health checks: Exposes HTTP endpoints to provide basic availability and state information about an app. Health checks are used to influence decisions made by container orchestrators, load balancers, API gateways, and other management services.

• Resiliency: The ability of your system to react to failure and still remain functional. Resiliency extends beyond preventing failures to include recovering and reconstructing your cloud-native environment back to a healthy state.

Versioning considerations

Hosting and client integrations are updated each release to target the latest stable versions of dependent resources. When container images are updated with new image versions, the hosting integrations update to these new versions. Similarly, when a new package version is available for a dependent client library, the corresponding client integration updates to the new version. This ensures the latest features and security updates are available to applications. The Aspire update type (major, minor, patch) doesn’t necessarily indicate the type of update in dependent resources. For example, a new major version of a dependent resource may be updated in a Aspire patch release, if necessary.

When major breaking changes happen in dependent resources, integrations may temporarily split into version-dependent packages to ease updating across the breaking change.