DebuggingMadeJoyful.Aspire.Hosting.Dart 1.0.0

DebuggingMadeJoyful.Aspire.Hosting.Dart library

Provides extension methods and resource definitions for an Aspire AppHost to configure Dart and Flutter application resources.

Getting started

Prerequisites

• Dart SDK: For Dart applications, ensure the Dart SDK is installed and available on your PATH.
• Flutter SDK: For Flutter applications, ensure the Flutter SDK is installed and available on your PATH.

Install the package

In your AppHost project, install the Aspire Dart Hosting library with NuGet:

dotnet add package DebuggingMadeJoyful.Aspire.Hosting.Dart

Usage example

Then, in the AppHost.cs file of AppHost, add a Dart or Flutter resource and consume the connection using the following methods:

Add a Dart Application

var builder = DistributedApplication.CreateBuilder(args);

// Add a Dart server application
var dartApi = builder.AddDartApp("api", "../dart-api", "bin/server.dart")
    .WithHttpEndpoint(port: 8080);

builder.Build().Run();

Add a Flutter Web Application

var builder = DistributedApplication.CreateBuilder(args);

// Add a Flutter web application
var flutter = builder.AddFlutterApp("frontend", "../flutter-web")
    .WithHttpEndpoint(port: 3000)
    .WithExternalHttpEndpoints();

builder.Build().Run();

Add a Flutter Desktop Application

var builder = DistributedApplication.CreateBuilder(args);

// Add a Flutter desktop application (auto-detects current platform)
var desktop = builder.AddFlutterDesktopApp("desktop-app", "../flutter-desktop");

// Or specify a target platform explicitly
var windowsApp = builder.AddFlutterDesktopApp("windows-app", "../flutter-desktop", "windows");

builder.Build().Run();

Compile-time Environment Variables

Flutter web applications cannot access traditional environment variables at runtime because they run in the browser. Use WithDartDefine to inject configuration at compile time:

var api = builder.AddProject<Projects.ApiService>("api");

// Inject values that Flutter can access via String.fromEnvironment
builder.AddFlutterApp("frontend", "../flutter-web")
    .WithDartDefine("API_URL", api.GetEndpoint("http"))
    .WithDartDefine("APP_VERSION", "1.0.0");

In your Flutter/Dart code:

const apiUrl = String.fromEnvironment('API_URL');
const appVersion = String.fromEnvironment('APP_VERSION', defaultValue: '0.0.0');

You can also load configuration from a file:

builder.AddFlutterApp("frontend", "../flutter-web")
    .WithDartDefineFromFile(".env.development");

OpenTelemetry Integration

Both Dart and Flutter applications are automatically configured to send OpenTelemetry telemetry data to the Aspire Dashboard. The integration works across all platforms:

• Desktop apps: Access OTEL configuration via Platform.environment
• Web apps: Access OTEL configuration via String.fromEnvironment (injected via --dart-define)

In your Dart/Flutter code, configure the OpenTelemetry SDK:

import 'dart:io' show Platform;

// Get OTEL configuration (works for both web and desktop)
String getOtelEndpoint() {
  // First try compile-time value (for web)
  const compileTime = String.fromEnvironment('OTEL_EXPORTER_OTLP_ENDPOINT');
  if (compileTime.isNotEmpty) return compileTime;
  
  // Fall back to runtime environment (for desktop)
  return Platform.environment['OTEL_EXPORTER_OTLP_ENDPOINT'] ?? '';
}

final otlpEndpoint = getOtelEndpoint();
final otlpProtocol = const String.fromEnvironment('OTEL_EXPORTER_OTLP_PROTOCOL');
final serviceName = const String.fromEnvironment('OTEL_SERVICE_NAME');

Add the opentelemetry package to your pubspec.yaml to use these values with the Dart OpenTelemetry SDK.

Automatic Dependency Management

By default, the integration will automatically run dart pub get or flutter pub get before starting your application if a pubspec.yaml file is found in the project directory.

To skip automatic dependency installation:

builder.AddDartApp("api", "../dart-api", "bin/server.dart")
    .WithoutPubGet();

Browser Configuration

For Flutter web applications, you can configure which browser to use for development:

// Use a specific browser
builder.AddFlutterApp("frontend", "../flutter-web")
    .WithBrowser(FlutterBrowser.Edge);

// Run in headless mode (no browser window)
builder.AddFlutterApp("frontend", "../flutter-web")
    .WithHeadlessMode();

// Use a specific port
builder.AddFlutterApp("frontend", "../flutter-web")
    .WithWebPort(3000);

Available browser options:

• FlutterBrowser.Chrome - Google Chrome (default)
• FlutterBrowser.Edge - Microsoft Edge
• FlutterBrowser.Firefox - Mozilla Firefox (experimental)

Headless mode is useful for automated testing scenarios or when running in CI/CD pipelines.

Supported Platforms

Additional documentation

• https://dart.dev/get-dart
• https://docs.flutter.dev/get-started/install
• https://github.com/dotnet/aspire/tree/main/src/Components/README.md

Feedback & contributing

https://github.com/dotnet/aspire