为 Durable Task Scheduler 中的业务流程协调和活动添加标签

标签是键值对，你可以附加到编排、活动和子编排上，以添加自定义元数据。在工作运行过程中使用标签来分类和关联。你也可以用编排标签来查询编排实例。

您可以为以下内容添加标签：

业务流程实例——当你从客户端启动新的业务流程时。
活动 — 当协调程序调度某个活动时。
子协调流程 — 当协调程序调度子协调流程时。

SDK 和扩展支持

SDK/扩展	业务流程标记	活动标签	子编排标签	阅读编排标签
Durable Task .NET SDK （`durabletask-dotnet`）	✅	✅	✅	✅
Durable Task JavaScript SDK （`durabletask-js`）	✅	✅	✅	✅
Durable Task Python SDK （`durabletask-python`）	✅	✅	❌	❌（未在 `OrchestrationState` 中显示）
Durable Task Java SDK （`durabletask-java`）	✅ （v1.6.0+）	❌（`TaskOptions` 仅用于重试）	❌	✅
Durable Functions：.NET 隔离进程	✅	✅	✅	✅
Durable Functions：.NET 进程内	❌	❌	❌	❌
Durable Functions：JavaScript	❌	❌	❌	❌
Durable Functions：Python	❌	❌	❌	❌
Durable Functions：Java	✅	❌	❌	✅

标记的工作原理

当你安排编排、活动或子编排时，可以提供字符串键值对的字典作为标签。持久任务调度器根据你标记的内容，以不同的方式存储和暴露标签：

编排标签 作为元数据存储在编排实例中。调用子编排时提供的标签会成为子编排实例的元数据。你可以读取这些标签，并按标签筛选编排实例。
活动标签 存储在父编排历史中的活动的计划事件中。你可以在编排历史中检查它们，但它们没有被索引，也没有在编排标签查询中出现。活动标签也不会传递给活动函数。

在安排编排、活动或子编排时设置标签。之后你不能更改标签。

设置自定义显示名称

使用常用的 durabletask.displayName 标记，为业务流程、子业务流程或活动指定一个供查看运行情况的人员使用的名称。当该标签值非空时，持久任务调度仪表盘会在通常显示注册名称的地方显示该值，包括编排列表、流程视图和顺序视图以及详细面板。

注册名称不会被丢弃或更改。它仍可在仪表板的工具提示和详细信息中查看到，而自定义显示名称不会影响实际运行的代码。如果标签缺失或空，仪表盘会像往常一样显示注册名称。

Important

durabletask.前缀保留给平台使用。仪表盘会在常规标签列表中隐藏键以 durabletask. 开头的标签，以便平台标签（如 durabletask.displayName）不会同时显示为解析后的元数据和原始标签。不要在 durabletask. 前缀下创建自定义标签键。

将标签添加到编排实例

var options = new StartOrchestrationOptions
{
    InstanceId = "order-12345",
    Tags = new Dictionary<string, string>
    {
        { "environment", "production" },
        { "tenant", "contoso" },
    },
};

string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
    "ProcessOrderOrchestration", input: order, options: options);

const instanceId = await client.scheduleNewOrchestration(
    "ProcessOrderOrchestration",
    order,
    {
        instanceId: "order-12345",
        tags: {
            environment: "production",
            tenant: "contoso",
        },
    }
);

instance_id = client.schedule_new_orchestration(
    "process_order_orchestration",
    input=order,
    instance_id="order-12345",
    tags={
        "environment": "production",
        "tenant": "contoso",
    },
)

NewOrchestrationInstanceOptions options = new NewOrchestrationInstanceOptions()
    .setInstanceId("order-12345")
    .setTags(Map.of(
        "environment", "production",
        "tenant", "contoso"
    ));

String instanceId = client.scheduleNewOrchestrationInstance(
    "ProcessOrderOrchestration", order, options);

向活动添加标记

var options = new TaskOptions(tags: new Dictionary<string, string>
{
    { "scheduleId", scheduleId },
});

await context.CallActivityAsync(nameof(CacheClearingActivity), options);

const result: string = yield ctx.callActivity(
    cacheClearingActivity,
    input,
    {
        tags: {
            scheduleId: scheduleId,
        },
    }
);

result = yield ctx.call_activity(
    "cache_clearing_activity",
    input=input_data,
    tags={
        "scheduleId": schedule_id,
    },
)

为子编排添加标签

var options = new SubOrchestrationOptions
{
    Tags = new Dictionary<string, string>
    {
        { "workflowType", "order-processing" },
    },
};

await context.CallSubOrchestratorAsync(
    "ValidateOrderOrchestration", input: order, options: options);

const result = yield ctx.callSubOrchestrator(
    validateOrderOrchestration,
    order,
    {
        tags: {
            workflowType: "order-processing",
        },
    }
);

阅读编排标签

OrchestrationMetadata? instance = await client.GetInstanceAsync(instanceId);

if (instance is not null)
{
    foreach (KeyValuePair<string, string> tag in instance.Tags)
    {
        Console.WriteLine($"{tag.Key} = {tag.Value}");
    }
}

const state = await client.getOrchestrationState(instanceId);

if (state) {
    for (const [key, value] of Object.entries(state.tags)) {
        console.log(`${key} = ${value}`);
    }
}

OrchestrationMetadata metadata = client.getInstanceMetadata(instanceId, false);

if (metadata != null) {
    Map<String, String> tags = metadata.getTags();
    for (Map.Entry<String, String> tag : tags.entrySet()) {
        System.out.println(tag.getKey() + " = " + tag.getValue());
    }
}

查询标记

在持久任务调度器仪表盘中，使用 标签过滤器 按编排标签过滤编排实例。该过滤器根据标签键或值进行匹配。编排列表还以列形式显示编排标签。

活动标签会出现在活动的计划事件中，出现在业务流程历史记录中。它们不包含在编排列表的 标签过滤器中。

持久任务调度程序仪表板的屏幕截图，显示了业务流程协调列表中的标记筛选器和标记列。

标签指南

使用一致的键 ——遵循命名规范，以便可靠地过滤编排实例并关联活动。
使标记有意义 — 使用提供上下文的值。
使用字符串值 — 键和值是字符串。
心智编排标签大小 ——完整的JSON序列化编排标签字典可达 1000字节。该限制包括所有键和值，并且多字节 UTF-8 字符每个都会按多个字节计算。活动标签不使用编排实例元数据限制，但它们会增加编排历史大小。

局限性

在业务流程、活动或子业务流程被计划后，标签将不可更改。
标记键和值是字符串。
你可以检查编排历史中的活动标签，但不能查询它们。你也不能把这些数据传递给活动函数。

后续步骤

实例管理

Last updated on 2026-08-14