add-dataverse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

📋 Shared Instructions: shared-instructions.md - Cross-cutting concerns.

References:

dataverse-reference.md - Picklist fields, virtual fields, lookups, file/image columns, form patterns (CRITICAL)
api-authentication-reference.md - Dataverse API auth, token, publisher prefix
table-management-reference.md - Query, create, extend tables and columns
data-architecture-reference.md - Relationship types, dependency tiers

📋 共享说明：shared-instructions.md - 跨领域关注点。

参考资料：

dataverse-reference.md - 选项列表字段、虚拟字段、查找、文件/图片列、表单模式（至关重要）
api-authentication-reference.md - Dataverse API 认证、令牌、发布者前缀
table-management-reference.md - 查询、创建、扩展表和列
data-architecture-reference.md - 关系类型、依赖层级

Add Dataverse

添加Dataverse

Two paths: existing tables (skip to Step 5) or new tables (full workflow).

两种路径：现有表（跳至步骤5）或新表（完整工作流）。

Workflow

工作流

Plan → 2. Setup API Auth → 3. Review Existing Tables → 4. Create Tables → 5. Add Data Source → 6. Review Generated Files → 7. Build

规划 → 2. 设置API认证 → 3. 查看现有表 → 4. 创建表 → 5. 添加数据源 → 6. 查看生成的文件 → 7. 构建

Step 1: Plan

步骤1：规划

Check memory bank for project context. Ask the user:

Which Dataverse table(s) do they need? (e.g.,
```
account
```
,
```
contact
```
,
```
cr123_customentity
```
)
Do the tables already exist in their environment, or do they need to create new ones?

If tables already exist: Skip to Step 5.

If creating new tables:

Ask about the data they need and design an appropriate schema
Use standard Dataverse tables when appropriate (
```
contact
```
for people,
```
account
```
for organizations)
Build a dependency graph -- see data-architecture-reference.md for tier classification
Enter plan mode with
```
EnterPlanMode
```
, present ER model with tables, columns, relationships, and creation order
Get approval with
```
ExitPlanMode
```

查看项目上下文的记忆库。询问用户：

他们需要哪些Dataverse表？（例如：
```
account
```
、
```
contact
```
、
```
cr123_customentity
```
）
这些表已存在于他们的环境中，还是需要新建？

如果表已存在： 跳至步骤5。

如果要创建新表：

询问用户所需的数据，并设计合适的架构
适当使用标准Dataverse表（如用
```
contact
```
存储人员信息，
```
account
```
存储组织信息）
构建依赖关系图——查看data-architecture-reference.md了解层级分类
使用
```
EnterPlanMode
```
进入规划模式，展示包含表、列、关系和创建顺序的ER模型
使用
```
ExitPlanMode
```
获取用户批准

Step 2: Setup API Auth (if creating tables)

步骤2：设置API认证（若创建表）

See api-authentication-reference.md for full details.

powershell

az account show   # Verify Azure CLI logged in

查看api-authentication-reference.md获取详细信息。

powershell

az account show   # 验证Azure CLI已登录

Find your Dataverse environment URL:

查找你的Dataverse环境URL：

In make.powerapps.com → Settings → Developer resources → Web API endpoint

在make.powerapps.com → 设置 → 开发人员资源 → Web API端点

It looks like: https://<org-name>.crm.dynamics.com/api/data/v9.2/

格式如下：https://<org-name>.crm.dynamics.com/api/data/v9.2/

Use the base URL: https://<org-name>.crm.dynamics.com

使用基础URL：https://<org-name>.crm.dynamics.com

$api = Initialize-DataverseApi -EnvironmentUrl "https://<org>.crm.dynamics.com" $headers = $api.Headers $baseUrl = $api.BaseUrl $publisherPrefix = $api.PublisherPrefix


Requires **System Administrator** or **System Customizer** security role.

$api = Initialize-DataverseApi -EnvironmentUrl "https://<org>.crm.dynamics.com" $headers = $api.Headers $baseUrl = $api.BaseUrl $publisherPrefix = $api.PublisherPrefix


需要**系统管理员**或**系统自定义员**安全角色。

Step 3: Review Existing Tables (if creating tables)

步骤3：查看现有表（若创建表）

Always query existing tables first before creating:

powershell

$existingTables = Invoke-RestMethod -Uri "$baseUrl/EntityDefinitions?`$filter=IsCustomEntity eq true&`$select=SchemaName,LogicalName,DisplayName" -Headers $headers

See table-management-reference.md for

Find-SimilarTables

Compare-TableSchemas

, and

Build-TableNameMapping

functions.

Present findings to user with

AskUserQuestion

Tables that can be reused (already exist with matching columns)
Tables that need extension (exist but missing columns)
Tables that must be created (no match found)

创建前务必先查询现有表：

powershell

$existingTables = Invoke-RestMethod -Uri "$baseUrl/EntityDefinitions?`$filter=IsCustomEntity eq true&`$select=SchemaName,LogicalName,DisplayName" -Headers $headers

查看table-management-reference.md了解

Find-SimilarTables

、

Compare-TableSchemas

和

Build-TableNameMapping

函数。

使用

AskUserQuestion

向用户展示结果：

可复用的表（已存在且列匹配）
需要扩展的表（已存在但缺少列）
必须创建的表（无匹配项）

Step 4: Create Tables (if creating tables)

步骤4：创建表（若创建表）

Get explicit confirmation before creating. Create in dependency order:

Tier 0: Reference tables (no dependencies)
Tier 1: Primary entities (reference Tier 0)
Tier 2: Dependent tables (reference Tier 1)

Use safe functions from table-management-reference.md:

```
New-DataverseTableIfNotExists
```
```
Add-DataverseColumnIfNotExists
```
```
Add-DataverseLookupIfNotExists
```
(from data-architecture-reference.md)

创建前需获得用户明确确认。按依赖顺序创建：

层级0：参考表（无依赖）
层级1：主实体（参考层级0）
层级2：依赖表（参考层级1）

使用table-management-reference.md中的安全函数：

```
New-DataverseTableIfNotExists
```
```
Add-DataverseColumnIfNotExists
```
```
Add-DataverseLookupIfNotExists
```
（来自data-architecture-reference.md）

Step 5: Add Data Source

步骤5：添加数据源

For each table:

bash

npx power-apps add-data-source -a dataverse -t <table-logical-name>

Can add multiple tables by running the command for each one.

针对每个表执行：

bash

npx power-apps add-data-source -a dataverse -t <table-logical-name>

可通过多次运行命令添加多个表。

Step 6: Review Generated Files

步骤6：查看生成的文件

The command generates:

src/generated/models/{Table}Model.ts

-- TypeScript interfaces, plus

{Table}FileColumnName

{Table}ImageColumnName

{Table}UploadColumnName

union types if the table has file/image columns

src/generated/services/{Table}Service.ts

-- CRUD methods (create, get, getAll, update, delete) plus

upload

downloadFile

downloadImage

deleteFileOrImage

if file/image columns exist

Show the user a usage example:

typescript

import { AccountsService } from "../generated/services/AccountsService";

const result = await AccountsService.getAll({
  select: ["name", "accountnumber"],
  filter: "statecode eq 0",
  orderBy: ["name asc"],
  top: 50
});
const accounts = result.data || [];

Key rules:

Use generated services (e.g.,
```
AccountsService.getAll()
```
), not fetch/axios
Check
```
result.data
```
for actual data
Don't edit generated files unless needed
Read dataverse-reference.md before writing any Dataverse code -- picklist fields, virtual fields, lookups, and file/image columns all have critical gotchas

该命令会生成：

src/generated/models/{Table}Model.ts

—— TypeScript接口，若表包含文件/图片列，还会生成

{Table}FileColumnName

、

{Table}ImageColumnName

、

{Table}UploadColumnName

联合类型

```
src/generated/services/{Table}Service.ts
```
—— CRUD方法（创建、获取、获取全部、更新、删除），若存在文件/图片列，还会包含
```
upload
```
、
```
downloadFile
```
、
```
downloadImage
```
、
```
deleteFileOrImage
```
方法

向用户展示使用示例：

typescript

import { AccountsService } from "../generated/services/AccountsService";

const result = await AccountsService.getAll({
  select: ["name", "accountnumber"],
  filter: "statecode eq 0",
  orderBy: ["name asc"],
  top: 50
});
const accounts = result.data || [];

关键规则：

使用生成的服务（例如：
```
AccountsService.getAll()
```
），而非fetch/axios
检查
```
result.data
```
获取实际数据
除非必要，否则不要编辑生成的文件
编写任何Dataverse代码前，请阅读dataverse-reference.md——选项列表字段、虚拟字段、查找和文件/图片列都有需要注意的关键问题

Step 7: Build

步骤7：构建

bash

npm run build

Fix TypeScript errors before proceeding. Do NOT deploy yet.

bash

npm run build

继续前修复TypeScript错误。暂不要部署。

Update Memory Bank

更新记忆库

Record which tables were added (or created), generated files, and any schema notes.

记录已添加（或创建）的表、生成的文件以及任何架构说明。