Set up Data API Builder in the AppHost

Dette indhold er ikke tilgængeligt i dit sprog endnu.

⭐ 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.

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.

aspire add CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder

Or add the package manually:

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

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

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.

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const sql: SqlServerServerResource
sql = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addSqlServer(name: string, options?: {
    password?: string | ParameterResource;
    port?: number;
}): SqlServerServerResource (+1 overload)
Adds a SQL Server resource to the application model. A container is used for local development.
addSqlServer('sql');
const 
const database: SqlServerDatabaseResource
database = await 
const sql: SqlServerServerResource
sql.
SqlServerServerResource.addDatabase(name: string, options?: {
    databaseName?: string;
} | undefined): SqlServerDatabaseResource (+1 overload)
Adds a SQL Server database resource
addDatabase('catalog');

const 
const dab: DataApiBuilderContainerResource
dab = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addDataAPIBuilder(name: string, options?: {
    configFilePaths?: string[];
    httpPort?: number;
}): DataApiBuilderContainerResource (+1 overload)
Adds a DataAPIBuilder application to the application model. Executes the pre-built containerized DataAPIBuilder engine.
addDataAPIBuilder('dab').
ContainerResource.withReference(source: EndpointReference | string | uri, options?: {
    connectionName?: string;
    optional?: boolean;
    name?: string;
} | undefined): DataApiBuilderContainerResource (+1 overload)
Adds a reference to another resource
withReference(
const database: SqlServerDatabaseResource
database);

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
Adds a node application to the application model. Node should be available on the PATH.
addNodeApp('web', './web', 'index.js').
ExecutableResource.withReference(source: EndpointReference | string | uri, options?: {
    connectionName?: string;
    optional?: boolean;
    name?: string;
} | undefined): NodeAppResource (+1 overload)
Adds a reference to another resource
withReference(
const dab: DataApiBuilderContainerResource
dab);

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

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();

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.

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:

{
  "$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.

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const dab: DataApiBuilderContainerResource
dab = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addDataAPIBuilder(name: string, options?: {
    configFilePaths?: string[];
    httpPort?: number;
}): DataApiBuilderContainerResource (+1 overload)
Adds a DataAPIBuilder application to the application model. Executes the pre-built containerized DataAPIBuilder engine.
addDataAPIBuilder('dab', {
  
configFilePaths?: string[] | undefined
configFilePaths: ['./dab-config.json', './dab-config.admin.json'],
});

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Customize the container image

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

TypeScript
C#

import { 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder } from './.aspire/modules/aspire.mjs';

const 
const builder: IDistributedApplicationBuilder
builder = await 
function createBuilder(): IDistributedApplicationBuilder
Creates a new distributed application builder
createBuilder();

const 
const dab: DataApiBuilderContainerResource
dab = await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.addDataAPIBuilder(name: string, options?: {
    configFilePaths?: string[];
    httpPort?: number;
}): DataApiBuilderContainerResource (+1 overload)
Adds a DataAPIBuilder application to the application model. Executes the pre-built containerized DataAPIBuilder engine.
addDataAPIBuilder('dab');
await 
const dab: DataApiBuilderContainerResource
dab.
ContainerResource.withImageRegistry(registry: string): DataApiBuilderContainerResource
Allows overriding the image registry on a container.
withImageRegistry('myregistry.azurecr.io');
await 
const dab: DataApiBuilderContainerResource
dab.
ContainerResource.withImage(image: string, options?: {
    tag?: string;
} | undefined): DataApiBuilderContainerResource (+1 overload)
Allows overriding the image on a container.
withImage('custom-dab');
await 
const dab: DataApiBuilderContainerResource
dab.
ContainerResource.withImageTag(tag: string): DataApiBuilderContainerResource
Allows overriding the image tag on a container.
withImageTag('1.0.0');

await 
const builder: IDistributedApplicationBuilder
builder.
IDistributedApplicationBuilder.build(): DistributedApplication
Builds the distributed application
build().
DistributedApplication.run(cancellationToken?: cancellationToken): void
Runs the distributed application
run();

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Use endpoint properties

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

TypeScript
C#

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();

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();

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.