用途
本技能为消费 salesforcedx-vscode-services 扩展 API 提供指南。适用于对 salesforcedx-vscode-services 具有 extensionDependency 的扩展,例如 salesforcedx-vscode-metadata、salesforcedx-vscode-org-browser。
获取 API
使用 @salesforce/effect-ext-utils 中的 ExtensionProviderService:
import { ExtensionProviderService, getServicesApi } from '@salesforce/effect-ext-utils';
const ExtensionProviderServiceLive = Layer.effect(
ExtensionProviderService,
Effect.sync(() => ({
getServicesApi
}))
);
// In an Effect.gen:
const api = yield * (yield * ExtensionProviderService).getServicesApi;
预构建服务与按扩展服务
api.services.prebuiltServicesDependencies 提供来自服务扩展激活时预构建的 Context.Context,用 Layer.succeedContext(...) 包装。它在扩展之间共享单例实例(缓存、监听器),避免重复构建有状态服务。
按扩展的层需要自行构建:
| Layer | 原因 |
|---|---|
| ChannelServiceLayer(displayName) | 自有输出通道 |
| ErrorHandlerService.Default | 依赖自有 ChannelService |
| ExtensionContextServiceLayer(context) | 自有 ExtensionContext |
| SdkLayerFor(context) | 自有 tracer(资源属性中包含扩展名称/版本) |
| ExtensionProviderServiceLive | 本地单例 |
ExtensionContext 设置
推荐方式:从 @salesforce/effect-ext-utils 导入 buildAllServicesLayer。它会从 package.json 读取 displayName,否则回退到第二个参数。services/extensionProvider.ts 只需要可变的 AllServicesLayer 加 setter:
// services/extensionProvider.ts
import { buildAllServicesLayer } from '@salesforce/effect-ext-utils';
export let AllServicesLayer: ReturnType<typeof buildAllServicesLayer>;
export const setAllServicesLayer = (layer: ReturnType<typeof buildAllServicesLayer>) => {
AllServicesLayer = layer;
};
在 activate 中传入 context 和本地化的回退通道名:
import { buildAllServicesLayer } from '@salesforce/effect-ext-utils';
import { nls } from './messages';
import { setAllServicesLayer } from './services/extensionProvider';
export const activate = async (context: vscode.ExtensionContext): Promise<void> => {
setAllServicesLayer(buildAllServicesLayer(context, nls.localize('channel_name')));
await getRuntime().runPromise(activateEffect(context));
};
遗留内联模式:本地 buildAllServicesLayer 工厂在 services/extensionProvider.ts 中把 Layer.unwrapEffect(...) 包装起来。改动这些代码时应迁移到共享 helper——去掉工厂,从 @salesforce/effect-ext-utils 导入 buildAllServicesLayer,在调用点传入回退名称。
运行时与 provide
- 应做:构建 ManagedRuntime.make(AllServicesLayer) 并导出 getRuntime()。
- 应做:使用 getRuntime().runPromise(effect) / runFork(effect) 进行临时执行。
- 不应做:在调用点使用 Effect.provide(AllServicesLayer)——应改用运行时。
- 例外:registerCommandWithLayer(AllServicesLayer)——保持传入 Layer,它在内部使用 provide。
注册命令
使用 registerCommandWithLayer(针对 Layer)或 registerCommandWithRuntime(针对运行时)。命令会自动注册到 ExtensionContext subscriptions、包装错误处理、用可观测 span 追踪、处理取消和成功处理。
Effect.fn 在 generator 之后接受中间件参数。把成功侧中间件放在 catchTag/catchAll 之前——否则被捕获的错误会变成成功。
调用 sf.org.login.web
跨扩展 / executeCommand:vscode.commands.executeCommand('sf.org.login.web', instanceUrl?, reauthAliasOrUsername?)。无参数时为交互式流程(命令面板)。带 instanceUrl 时跳过组织类型快速选择。第二个参数仅在提供 instanceUrl 时生效:去除空白的非空字符串成为认证别名(access-token 重新认证);否则别名默认为 reauth-vscodeOrg。
基础服务
采用访问器模式:直接调用方法,不要先赋值给变量。
- ChannelService — 输出通道
- ComponentSetService — 构建组件集(source、manifest、URI)
- MediaService — 图标(ICONS)和 NLS 描述
- WorkspaceService — 工作区信息
- ConnectionService — 组织连接
- ProjectService — 项目解析、packageDirectories
- SettingsService — 设置读写
- FsService — 文件操作(web 兼容)及 uri/path 转换
- EditorService — 活动编辑器变更及当前 URI
- Prompts — QuickPick、InputBox 以及 UserCancellationError 处理
- TerminalService — 运行 shell 命令(仅桌面)
监听器
文件监听:FileWatcherService 暴露所有工作区文件变更(**/*)的 PubSub,可订阅并过滤。
配置监听:使用 PubSub.sliding 与 vscode.workspace.onDidChangeConfiguration 监听 VS Code 配置变更,配合 Effect.addFinalizer 清理 disposable,并可加 Stream.debounce。
目标组织变更:通过 TargetOrgRef(SubscriptionRef)监听组织变更。ref.changes 总是先发出当前值作为第 0 个元素,然后是后续变更,不要手动前置显式 get。如需抑制初始快照(例如避免在树提供器就绪前触发刷新),使用 Stream.drop(1)。
Ref 行为:默认组织更新时,若 User SOQL 中存在 username 则使用,否则使用连接上的 AuthInfo 登录用户名。无 username 的 TargetOrgRef 快照,在视为无目标组织之前可先尝试可选的 ConfigUtil.getUsername()(项目默认值)——参见 salesforcedx-vscode-org orgDisplay。TargetOrgRef 的值始终是对象(永不为 undefined);只有其中的 orgId 等字段是可选的。
常见模式
- 从 Layer.succeedContext(api.services.prebuiltServicesDependencies) 开始——不要为已在其中的服务添加单独的 *.Default。
- 只在其上添加按扩展的层。
- 在 Effect 外使用 ICONS,在 Effect 内使用 MediaService。
- ChannelServiceLayer 放在 ErrorHandlerService 之前。
- 向 SdkLayerFor 传入 context(从 ExtensionContext 提取名称/版本)。
- 使用 Effect.forkIn(..., yield* getExtensionScope()) 以便在停用时清理监听器。
- 所有命令都用 registerCommandWithLayer(追踪 + 错误处理)。
- 使用 getRuntime().runPromise / runFork 执行,而不是 Effect.provide(AllServicesLayer)。
- 不要重建已在 prebuiltServicesDependencies 中的服务:对其中任一服务调用 .Default 会创建第二个实例,带来自己的缓存、监听器和状态,静默破坏跨扩展共享。
审查
对计划和 diff 调用 effect-advocate 子代理——其最高优先级的发现类别是“你重新实现了 salesforcedx-vscode-services 中已存在的东西”。
prebuiltServicesDependencies 包含约 27 个在服务扩展激活期间一次性构建的服务。