Data API builder integration

Questi contenuti non sono ancora disponibili nella tua lingua.

⭐ Community Toolkit

This article is the reference for the Aspire Data API Builder hosting integration. It enumerates the AppHost APIs that you use to model a Data API Builder (DAB) resource in your AppHost project. DAB is an open-source tool that generates REST and GraphQL APIs directly from your database schema.

Installation

To start building an Aspire app that uses Data API Builder, install the 📦 CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder NuGet package:

aspire add CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

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

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

aspire add CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the Data API Builder hosting integration package:

{
  "packages": {
    "CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder": "*"
  }
}

The TypeScript AppHost bindings for Data API Builder are provided by the Community Toolkit package. After installation, the .aspire/modules/aspire.mjs file in your project includes addDataAPIBuilder and related APIs.

Add Data API Builder resource

Once you’ve installed the hosting integration in your AppHost project, you can add a Data API Builder resource and reference a database as shown in the following example:

var builder = DistributedApplication.CreateBuilder(args);

var sqldb = builder.AddSqlServer("sql")
    .AddDatabase("sqldb");

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

builder.AddProject<Projects.ExampleProject>("example-project")
    .WithReference(dab);

// After adding all resources, run the app...
builder.Build().Run();

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

const builder = await createBuilder();

const sqldb = await (await builder.addSqlServer("sql")).addDatabase("sqldb");

const dab = await builder.addDataAPIBuilder("dab");
await dab.withReference(sqldb);

const exampleProject = await builder.addProject(
    "example-project",
    "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(dab);

// After adding all resources, run the app...

The Data API Builder integration automatically discovers and uses dab-config.json configuration files in your project.

Multiple configuration files

Data API Builder supports multiple configuration files for different databases. To specify multiple configuration files, pass an array of config file paths to AddDataAPIBuilder or addDataAPIBuilder:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
    .AddDatabase("sqldb");

var postgres = builder.AddPostgres("postgres")
    .AddDatabase("postgresdb");

var dab = builder.AddDataAPIBuilder("dab", ["dab-config.SqlServer.json", "dab-config.PostgreSQL.json"])
    .WithReference(sql)
    .WithReference(postgres);

// After adding all resources, run the app...
builder.Build().Run();

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

const builder = await createBuilder();

const sql = await (await builder.addSqlServer("sql")).addDatabase("sqldb");
const postgres = await (await builder.addPostgres("postgres")).addDatabase("postgresdb");

const dab = await builder.addDataAPIBuilder("dab", {
    configFilePaths: ["dab-config.SqlServer.json", "dab-config.PostgreSQL.json"],
});
await dab.withReference(sql);
await dab.withReference(postgres);

// After adding all resources, run the app...

Custom container images

To use a custom Data API Builder container image, use the container image methods:

var builder = DistributedApplication.CreateBuilder(args);

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

// After adding all resources, run the app...
builder.Build().Run();

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

// After adding all resources, run the app...

Database references

Data API Builder requires references to the databases it exposes. Use WithReference or withReference to connect Data API Builder to your databases:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
    .AddDatabase("sqldb");

var cosmos = builder.AddAzureCosmosDB("cosmos")
    .AddDatabase("cosmosdb");

var dab = builder.AddDataAPIBuilder("dab")
    .WithReference(sql)
    .WithReference(cosmos);

// After adding all resources, run the app...
builder.Build().Run();

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

const builder = await createBuilder();

const sql = await (await builder.addSqlServer("sql")).addDatabase("sqldb");
const cosmos = await (await builder.addAzureCosmosDB("cosmos")).addCosmosDatabase("cosmosdb");

const dab = await builder.addDataAPIBuilder("dab");
await dab.withReference(sql);
await dab.withReference(cosmos);

// After adding all resources, run the app...

Configuration file structure

Data API Builder uses dab-config.json files to define the API. The following is an example configuration:

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

The Aspire integration automatically injects the database connection strings from the referenced resources into the running container.

Endpoints

Data API Builder exposes two endpoints:

REST API: Available at /api by default
GraphQL API: Available at /graphql by default

Both endpoints are configured in the dab-config.json file.