generating-ui-bundle-custom-app

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Custom Application for React UI Bundles

用于React UI Bundles的Custom Application

Create and configure a Salesforce Custom Application that hosts a React UI bundle in Lightning Experience. This skill generates the CustomApplication metadata so the app appears in the Lightning App Launcher and can be accessed by internal users.

Custom Applications differ from Experience Sites: they don't need Networks, CustomSite, DigitalExperienceConfig, or DigitalExperienceBundle metadata. The Custom Application acts as a thin launcher entry that delegates rendering to the React UI bundle referenced by

uiBundle

创建并配置Salesforce Custom Application，以在Lightning Experience中托管React UI Bundle。此技能生成CustomApplication元数据，使应用显示在Lightning应用启动器中，供内部用户访问。

Custom Application与Experience Sites不同：它们不需要Networks、CustomSite、DigitalExperienceConfig或DigitalExperienceBundle元数据。Custom Application作为一个轻量启动入口，将渲染委托给由

uiBundle

引用的React UI Bundle。

Required Properties

必填属性

Resolve all properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.

Property	Format	How to Resolve
appName	`lowercamelcase` (e.g., `myInternalApp` )	The UI bundle name from `uiBundles/<name>/` directory
appNamespace	String	`namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c`
appLabel	Human-readable string	User-provided, or derive from appName by converting camelCase to Title Case

The

appNamespace

and

appName

connect the Custom Application to the correct React UI bundle. In newer API versions this uses

<uiBundle>{appNamespace}__{appName}</uiBundle>

; in older versions it uses

<webApplication>{appName}</webApplication>

. Getting this wrong means the app launcher entry exists but shows a blank page. Step 2 of the workflow determines which field to use.

在生成任何元数据之前解析所有属性。每个属性都有一个回退链——按顺序尝试每个选项，直到找到值。

属性	格式	解析方式
appName	`lowercamelcase` （例如： `myInternalApp` ）	从 `uiBundles/<name>/` 目录中获取UI bundle名称
appNamespace	字符串	`sfdx-project.json` 中的 `namespace` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → 默认值 `c`
appLabel	易读字符串	用户提供，或通过将appName的驼峰式转换为标题式来推导

appNamespace

和

appName

将Custom Application连接到正确的React UI Bundle。在较新的API版本中，使用

<uiBundle>{appNamespace}__{appName}</uiBundle>

；在较旧版本中，使用

<webApplication>{appName}</webApplication>

。如果配置错误，应用启动器条目会存在，但显示空白页面。工作流的第2步将确定使用哪个字段。

Generation Workflow

生成工作流

Step 1: Resolve All Required Properties

步骤1：解析所有必填属性

Determine values for all properties before constructing anything. Use the resolution strategies in the table above.

在构建任何内容之前确定所有属性的值。使用上表中的解析策略。

Step 2: Query API Context (Version-Aware Field Discovery)

步骤2：查询API上下文（基于版本的字段发现）

Call

salesforce-api-context

MCP tools to discover which fields exist for the target org's API version. This ensures the generated metadata is compatible with the user's Salesforce version.

Required calls:

Call

get_metadata_type_fields

for

CustomApplication

— check whether the

uiBundle

field exists

Call
```
get_metadata_type_fields
```
for
```
UIBundle
```
— check whether the
```
target
```
field exists

Field resolution based on API response:

Field Check	If present	If absent (older API version)
`CustomApplication.uiBundle`	Use `<uiBundle>{appNamespace}__{appName}</uiBundle>`	Use `<webApplication>{appName}</webApplication>` (no namespace)
`UIBundle.target`	Use `<target>CustomApplication</target>`	Omit the `<target>` element entirely

salesforce-api-context

is unavailable after a real attempt, fall back to the newer field names (

uiBundle

target

调用

salesforce-api-context

MCP工具，发现目标组织API版本支持的字段。这确保生成的元数据与用户的Salesforce版本兼容。

必填调用：

调用
```
get_metadata_type_fields
```
获取
```
CustomApplication
```
的字段——检查
```
uiBundle
```
字段是否存在
调用
```
get_metadata_type_fields
```
获取
```
UIBundle
```
的字段——检查
```
target
```
字段是否存在

基于API响应的字段解析：

字段检查	存在时	不存在时（旧API版本）
`CustomApplication.uiBundle`	使用 `<uiBundle>{appNamespace}__{appName}</uiBundle>`	使用 `<webApplication>{appName}</webApplication>` （无命名空间）
`UIBundle.target`	使用 `<target>CustomApplication</target>`	完全省略 `<target>` 元素

如果尝试后仍无法使用

salesforce-api-context

，则回退到较新的字段名称（

uiBundle

target

）。

Step 3: Create the Project Structure

步骤3：创建项目结构

Create any files and directories that don't already exist:

Metadata Type	Path
CustomApplication	`<sourceDir>/applications/{appName}.app-meta.xml`

Note:

<sourceDir>

is determined from

sfdx-project.json

. Read

packageDirectories[]

and use the entry where

"default": true

; the full source directory is

<path>/main/default

. If no default is set, use the first entry. Commonly

force-app/main/default

, but this path is configurable.

创建所有不存在的文件和目录：

元数据类型	路径
CustomApplication	`<sourceDir>/applications/{appName}.app-meta.xml`

注意：

<sourceDir>

由

sfdx-project.json

确定。读取

packageDirectories[]

并使用

"default": true

的条目；完整的源目录为

<path>/main/default

。如果未设置默认值，则使用第一个条目。通常为

force-app/main/default

，但此路径可配置。

Step 4: Populate All Metadata Fields

步骤4：填充所有元数据字段

Use the default template in the doc below. Values in

{braces}

are resolved property references — substitute them with the actual values from Step 1. Apply the field resolution from Step 2 to determine which XML elements to use.

Metadata Type	Template Reference
CustomApplication	configure-metadata-custom-application.md

使用下方文档中的默认模板。

{braces}

中的值是解析后的属性引用——用步骤1中的实际值替换它们。应用步骤2中的字段解析来确定使用哪些XML元素。

元数据类型	模板参考
CustomApplication	configure-metadata-custom-application.md

Execution Note for Step 4: Load and use the doc

步骤4执行说明：加载并使用文档

Agents MUST read the full contents of the docs/*.md file referenced in Step 4 before attempting to populate metadata fields.
Read the file in full, replace placeholders (e.g.
```
{appName}
```
) with the resolved values, then use the expanded template to populate the metadata XML content.
If Step 2 determined the older field names apply, substitute
```
<uiBundle>
```
with
```
<webApplication>
```
in the generated output.

Agent必须在尝试填充元数据字段之前，完整阅读步骤4中引用的docs/*.md文件的全部内容。
完整阅读文件，将占位符（例如
```
{appName}
```
）替换为解析后的值，然后使用展开后的模板填充元数据XML内容。
如果步骤2确定应使用旧字段名称，则在生成的输出中将
```
<uiBundle>
```
替换为
```
<webApplication>
```
。

Step 5: Update UI Bundle Meta XML

步骤5：更新UI Bundle元XML

If Step 2 confirmed the

target

field exists on

UIBundle

, add

<target>CustomApplication</target>

to the

.uibundle-meta.xml

file (skip if the field doesn't exist in the org's API version):

xml

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>{appName}</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

如果步骤2确认

UIBundle

支持

target

字段，则将

<target>CustomApplication</target>

添加到

.uibundle-meta.xml

文件中（如果组织的API版本不支持该字段则跳过）：

xml

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>{appName}</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

Step 6: Do Not Modify Non-Templated Properties

步骤6：不要修改非模板化属性

Do not modify any default property values for

CustomApplication

metadata that are not expressed as variables wrapped in

{braces}

不要修改CustomApplication元数据中所有未用

{braces}

包裹的变量表示的默认属性值。

Verification Checklist

验证清单

Before deploying, confirm:

All required properties are resolved
API context was queried to determine available fields (Step 2)
```
applications/{appName}.app-meta.xml
```
exists with correct content
The bundle reference field matches the org's API version (
```
<uiBundle>
```
or
```
<webApplication>
```
)

target

field is supported:

.uibundle-meta.xml

has

<target>CustomApplication</target>

Deployment validates successfully:

bash

sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}

部署前确认：

所有必填属性已解析
已查询API上下文以确定可用字段（步骤2）
```
applications/{appName}.app-meta.xml
```
已存在且内容正确
bundle引用字段与组织的API版本匹配（
```
<uiBundle>
```
或
```
<webApplication>
```
）

如果支持

target

字段：

.uibundle-meta.xml

包含

<target>CustomApplication</target>

部署验证成功：

bash

sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}