Set up Data API Builder in the AppHost

⭐ Community Toolkit

This article is the AppHost API reference for the 📦 CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder package. Start with Get started with Data API Builder for the integration workflow, or see Connect Aspire apps to Data API Builder for consuming-app examples.

Installation

C#

Terminal

aspire add CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder

Or add the package manually:

AppHost.cs

#:package CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder@*

AppHost.csproj

<PackageReference Include="CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder" Version="*" />

TypeScript

Terminal

aspire add CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder

This adds the package to aspire.config.json. After aspire restore, .aspire/modules/aspire.mjs includes addDataAPIBuilder and the exported resource properties.

Learn more about aspire add and aspire restore.

Add a Data API Builder resource

The integration uses dab-config.json by default. The file must exist when the AppHost builds the application model.

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var database = builder.AddSqlServer("sql")
    .AddDatabase("catalog");

var dab = builder.AddDataAPIBuilder("dab")
    .WithReference(database);

builder.AddProject<Projects.Web>("web")
    .WithReference(dab);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const sql = await builder.addSqlServer('sql');
const database = await sql.addDatabase('catalog');

const dab = await builder.addDataAPIBuilder('dab').withReference(database);

await builder.addNodeApp('web', './web', 'index.js').withReference(dab);

await builder.build().run();

The integration runs mcr.microsoft.com/azure-databases/data-api-builder:1.6.77, maps the container’s port 5000 to an Aspire-managed HTTP endpoint, enables OTLP export, and checks /health.

Note

Data API Builder exposes HTTP only through this integration. The source defines HTTPS constants but does not register an HTTPS endpoint.

Configure database connections

Reference each database resource from DAB, then read the Aspire-injected connection string in dab-config.json. For a database resource named catalog, use ConnectionStrings__catalog:

dab-config.json

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.6.77/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('ConnectionStrings__catalog')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql"
    }
  },
  "entities": {
    "Product": {
      "source": "dbo.Products",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        }
      ]
    }
  }
}

The REST route for this entity is /api/Product; GraphQL requests use /graphql.

Mount multiple configuration files

Pass every configuration path to AddDataAPIBuilder or addDataAPIBuilder. Each file is mounted read-only under /App in the container.

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var dab = builder.AddDataAPIBuilder(
    "dab",
    ["dab-config.json", "dab-config.admin.json"]);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const dab = await builder.addDataAPIBuilder('dab', {
  configFilePaths: ['./dab-config.json', './dab-config.admin.json'],
});

await builder.build().run();

Customize the container image

The DAB resource is a standard container resource, so you can replace the registry, image, or tag:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var dab = builder.AddDataAPIBuilder("dab")
    .WithImageRegistry("myregistry.azurecr.io")
    .WithImage("custom-dab")
    .WithImageTag("1.0.0");

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const dab = await builder.addDataAPIBuilder('dab');
await dab.withImageRegistry('myregistry.azurecr.io');
await dab.withImage('custom-dab');
await dab.withImageTag('1.0.0');

await builder.build().run();

Use endpoint properties

The resource exports its primary endpoint, host, port, and URI expression for use in custom AppHost expressions:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var dab = builder.AddDataAPIBuilder("dab");
var primaryEndpoint = dab.Resource.PrimaryEndpoint;
var host = dab.Resource.Host;
var port = dab.Resource.Port;
var uri = dab.Resource.UriExpression;

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const dab = await builder.addDataAPIBuilder('dab');
const primaryEndpoint = await dab.primaryEndpoint();
const host = await dab.host();
const port = await dab.port();
const uri = await dab.uriExpression();

await builder.build().run();

Hosting integration health checks

The hosting integration automatically adds an HTTP health check for /health. Aspire uses it to report when the DAB resource is ready.

See also

• Connect Aspire apps to Data API Builder
• Data API Builder configuration
• REST API in Data API Builder
• GraphQL in Data API Builder