命令行工具

数据墙DBW 提供了一个 dab 命令行工具，用于创建配置、管理实体、修改设置、启动服务和校验配置。所有对 JSON 配置文件的修改都可以通过 CLI 完成，无需手动编辑 JSON。

安装

dab 通过 .NET 工具分发：

dotnet tool install --global Microsoft.DataApiBuilder

更新到最新版：

dotnet tool update --global Microsoft.DataApiBuilder

验证安装：

dab --version

dab init — 初始化配置

创建一个新的配置文件，指定数据库类型和连接信息：

dab init \
  --database-type "mssql" \
  --connection-string "@env('SQL_CONN_STRING')" \
  --host-mode "Development" \
  --config "dab-config.json"

常用参数

参数	说明	默认值
--database-type	数据库类型：mssql、postgresql、mysql	—
--connection-string	数据库连接字符串，支持 @env()	—
--host-mode	运行模式：Development 或 Production	Production
--config	输出的配置文件名	dab-config.json
--auth.provider	身份验证提供程序	Unauthenticated
--auth.issuer	JWT issuer（Custom 提供程序时使用）	—
--auth.audience	JWT audience（Custom 提供程序时使用）	—
--graphql.enabled	是否启用 GraphQL	true
--graphql.path	GraphQL 端点前缀	/graphql
--graphql.multiple-create.enabled	允许多个 create mutation	false
--rest.enabled	是否启用 REST	true
--rest.path	REST 端点前缀	/api
--rest.request-body-strict	严格校验请求体	false
--mcp.enabled	是否启用 MCP	true
--mcp.path	MCP 端点前缀	/mcp
--mcp.aggregate-records.query-timeout	aggregate-records 工具超时（秒，1-600）	30
--runtime.base-route	所有端点的全局前缀（需配合 --auth.provider StaticWebApps）	—
--cors-origin	允许的跨域来源（逗号分隔）	—
--set-session-context	启用 SQL Server 会话上下文	false

WARNING

如果目标配置文件已存在，dab init 会直接覆盖，不会合并。如需保留旧文件，请先备份或使用版本控制。

dab add — 添加实体

将数据库对象注册为 API 实体：

# 添加表实体
dab add Book \
  --source "dbo.books" \
  --permissions "anonymous:read"

# 添加视图实体，指定主键
dab add BookDetail \
  --source "dbo.vw_books_details" \
  --source.type "view" \
  --fields.name "id" \
  --fields.primary-key "true" \
  --permissions "anonymous:read"

# 添加存储过程实体
dab add GetBookById \
  --source "dbo.get_book_by_id" \
  --source.type "stored-procedure" \
  --parameters.name "id" \
  --parameters.required "true" \
  --permissions "anonymous:execute" \
  --rest.methods "GET" \
  --graphql.operation "query"

常用参数

参数	说明
--source	数据库对象名称（schema.name）
--source.type	对象类型：table（默认）、view、stored-procedure
--permissions	权限配置，格式 "角色:操作"，多个用逗号分隔
--fields.name	数据库字段名
--fields.alias	API 中的字段别名
--fields.primary-key	标记主键字段（true / false）
--rest.path	自定义 REST 路径
--rest.methods	允许的 HTTP 方法（仅存储过程）
--rest.enabled	启用或禁用 REST
--graphql.enabled	启用或禁用 GraphQL
--graphql.operation	存储过程挂载位置：query / mutation
--graphql.type.singular	GraphQL 单数类型名
--graphql.type.plural	GraphQL 复数类型名
--fields.name	数据库字段名
--fields.alias	API 中的字段别名
--fields.primary-key	标记主键字段（true / false）
--fields.include	允许暴露的字段列表
--fields.exclude	排除的字段列表
--description	实体说明，供 MCP 和文档使用
--parameters.name	存储过程参数名
--parameters.required	是否必需（true / false）
--parameters.default	参数默认值
--cache.enabled	启用实体缓存
--cache.ttl-seconds	缓存生存时间（秒）
--cache.level	缓存层级：L1 / L1L2
--mcp.dml-tools	是否暴露 MCP DML 工具
--mcp.custom-tool	是否注册为 MCP 自定义工具（仅存储过程）
--health.enabled	启用实体健康检查

权限格式

"角色:操作,角色:操作"

示例：
"anonymous:read"
"anonymous:read,authenticated:*"

dab update — 更新实体

修改已存在的实体配置，参数与 dab add 基本一致：

# 修改权限
dab update Book --permissions "authenticated:*"

# 添加关系
dab update Book \
  --relationship book_category \
  --target.entity Category \
  --cardinality one \
  --relationship.fields "category_id:id"

# 启用缓存
dab update Product --cache.enabled true --cache.ttl-seconds 60

dab configure — 修改运行时配置

修改 runtime 块中的全局设置：

# 设置运行模式
dab configure --runtime.host.mode "production"

# 关闭 GraphQL
dab configure --runtime.graphql.enabled false

# 设置分页
dab configure --runtime.pagination.default-page-size 50

# 配置身份验证
dab configure --runtime.host.authentication.provider "Custom" \
  --runtime.host.authentication.jwt.issuer "https://idp.example.com" \
  --runtime.host.authentication.jwt.audience "dab-api"

# 配置日志级别
dab configure --runtime.telemetry.log-level.default "Warning"

# 启用文件遥测
dab configure --runtime.telemetry.file_enabled true

# 配置遥测文件路径
dab configure --runtime.telemetry.file.path "/var/log/dab-telemetry.json"

# 配置请求体严格校验
dab configure --runtime.rest.request-body-strict true

# 配置 GraphQL 路径
dab configure --runtime.graphql.path "/api/graphql"

dab start — 启动服务

dab start

常用参数

参数	说明
--config	指定配置文件路径。默认查找 dab-config.json，但如果存在 dab-config.<DAB_ENVIRONMENT>.json 则优先使用
--LogLevel	覆盖日志级别（Trace–Critical）
--verbose	等同于 --LogLevel Information
--no-https-redirect	禁用 HTTP→HTTPS 自动重定向
--mcp-stdio	以 MCP Stdio 传输模式启动（而非 HTTP），需启用 MCP。强制使用 Simulator 认证、UTF-8 编码、不绑定 HTTP 端口。支持 --mcp-stdio role:authenticated 指定角色

配合 DAB_ENVIRONMENT 环境变量加载不同环境配置：

DAB_ENVIRONMENT=Production dab start

dab validate — 校验配置

检查配置文件的语法正确性和引用完整性：

dab validate --config ./dab-config.json

校验内容包括：

• JSON 语法是否正确。
• 字段名和类型是否符合 Schema 定义。
• 数据源配置是否完整（database-type 和 connection-string 必须存在）。
• 实体引用是否有效（source.object 格式、permissions.role 合法）。
• 关系引用是否指向存在的实体。
• 配置文件路径引用是否有效（data-source-files）。

成功：无输出，退出码 0。失败：输出错误详情。

TIP

建议将 dab validate 加入 CI/CD 流水线，部署前自动校验配置，防止错误配置上线。

dab auto-config — 自动实体发现

扫描数据库并将所有匹配的表自动生成 autoentities 配置：

dab auto-config \
  --database-type "mssql" \
  --connection-string "Server=localhost;Database=todos;..." \
  --config "dab-config.json"

预览模式

dab auto-config-simulate \
  --database-type "mssql" \
  --connection-string "Server=localhost;Database=todos;..."

auto-config-simulate 只输出哪些表会被匹配，不修改配置文件。适合在正式执行前确认匹配范围。

常用参数

参数	说明
--database-type	数据库类型
--connection-string	连接字符串
--config	目标配置文件
--autoentities.include	包含模式（SQL LIKE 语法）
--autoentities.exclude	排除模式
--autoentities.name	实体命名模板（{schema}_{object}）
--autoentities.rest.enabled	匹配实体是否启用 REST
--autoentities.graphql.enabled	匹配实体是否启用 GraphQL
--autoentities.mcp.dml-tools	匹配实体是否启用 MCP 工具
--autoentities.cache.enabled	匹配实体是否启用缓存
--autoentities.permissions	匹配实体的默认权限
--csv-output	以 CSV 格式输出匹配结果（预览模式）

命令速查

命令	用途	修改配置文件
init	创建新配置文件	是（覆盖）
add	添加实体	是
update	修改实体配置	是
configure	修改运行时配置	是
start	启动服务	否
validate	校验配置文件	否
auto-config	生成 autoentities	是
auto-config-simulate	预览 auto-config 匹配结果	否
export	导出配置	否

下一步

• 配置数据源 — 连接字符串配置。
• 使用 REST API — CLI 配置完成后如何调用 API。