Hinzufügen von Tags zu Orchestrierungen und Aktivitäten in "Durable Task Scheduler"

Tags sind Schlüssel-Wert-Paare, die man Orchestrierungen, Aktivitäten und Sub-Orchestrierungen anhängen kann, um benutzerdefinierte Metadaten hinzuzufügen. Verwenden Sie Tags, um Arbeiten während der Ausführung zu kategorisieren und in Beziehung zu setzen. Man kann auch Orchestrierungs-Tags verwenden, um Orchestrierungsinstanzen abzufragen.

Sie können Tags hinzufügen zu:

• Orchestrierungsinstanzen — wenn Sie eine neue Orchestrierung durch den Client starten.
• Aktivitäten – wenn ein Orchestrator eine Aktivität plant.
• Unterorchestrierungen – wenn ein Orchestrator eine untergeordnete Orchestrierung einplant.

SDK- und Erweiterungsunterstützung

Funktionsweise von Tags

Wenn Sie eine Orchestrierung, Aktivität oder Suborchestrierung planen, können Sie ein Wörterbuch von String-Schlüssel-Wert-Paaren als Tags bereitstellen. Der Durable Task Scheduler speichert und zeigt Tags unterschiedlich, je nachdem, was du markierst:

• Orchestrierungs-Tags werden als Metadaten auf der Orchestrierungsinstanz gespeichert. Tags, die Sie beim Aufruf einer Suborchestrierung bereitstellen, werden zu Metadaten auf der Child Orchestration Instance. Du kannst diese Tags lesen und Orchestrierungsinstanzen nach Tag filtern.
• Aktivitäts-Tags werden im geplanten Ereignis der Aktivität im Verlauf der übergeordneten Orchestrierung gespeichert. Man kann sie in der Orchestrierungshistorie einsehen, aber sie sind nicht indexiert oder in Orchestrierungs-Tag-Abfragen verfügbar. Aktivitätstags werden ebenfalls nicht an die Aktivitätsfunktion weitergegeben.

Legen Sie Tags fest, wenn Sie die Orchestrierung, Aktivität oder Suborchestrierung planen. Du kannst die Tags danach nicht mehr ändern.

Setzen Sie einen benutzerdefinierten Anzeigenamen ein

Verwenden Sie das bekannte durabletask.displayName-Tag, um einer Orchestrierung, Unterorchestrierung oder Aktivität einen Namen zu geben, der für Personen gedacht ist, die eine Ausführung ansehen. Wenn dieses Tag keinen leeren Wert hat, zeigt das Dashboard „Langlebiger Aufgabenplaner“ diesen Wert an allen Stellen an, an denen andernfalls der registrierte Name angezeigt würde, einschließlich der Orchestrierungsliste, der Flow- und Sequenzansichten sowie der Detailbereiche.

Der eingetragene Name wird nicht verworfen oder geändert. Sie bleibt im Dashboard-Tooltip und in den Details verfügbar, und der benutzerdefinierte Anzeigename beeinflusst nicht, welcher Code ausgeführt wird. Wenn das Tag fehlt oder leer ist, zeigt das Dashboard den registrierten Namen wie gewohnt an.

Tags zu einer Orchestrierungsinstanz hinzufügen

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);

Hinzufügen von Tags zu einer Aktivität

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,
    },
)

Tags zu einer Unterorchestrierung hinzufügen

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",
        },
    }
);

Orchestrierungs-Tags auslesen

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());
    }
}

Abfragetags

Im Dashboard des Durable Task Scheduler verwenden Sie den Tag-Filter, um Orchestrierungsinstanzen nach Orchestrierungs-Tag zu filtern. Der Filter gleicht mit dem Tag-Schlüssel oder dem Wert ab. Die Orchestrierungsliste zeigt außerdem Orchestrierungstags als Spalte an.

Aktivitätstags erscheinen im geplanten Ereignis der Aktivität im Orchestrierungsverlauf. Sie sind nicht im Tag-Filter der Orchestrierungsliste enthalten.

Tagrichtlinien

• Verwenden Sie konsistente Keys – Folgen Sie einer Namenskonvention, damit Sie Orchestrierungsinstanzen zuverlässig filtern und Aktivitäten korrelieren können.
• Kategorien sinnvoll beibehalten – Verwenden Sie Werte, die Kontext bereitstellen.
• Verwenden Sie Zeichenfolgenwerte – Schlüssel und Werte sind Zeichenfolgen.
• Mind-Orchestrations-Tag-Größe — Das vollständige JSON-serialisierte Orchestrierungs-Tag-Wörterbuch kann bis zu 1.000 Bytes umfassen. Diese Begrenzung umfasst alle Schlüssel und Werte, und Multibyte-UTF-8-Zeichen zählen jeweils als mehr als ein Byte. Aktivitäts-Tags verwenden dieses Beschränkung für Metadaten für Orchestrierungsinstanzen nicht, tragen aber zur Größe des Orchestrierungsverlaufs bei.

Einschränkungen

• Tags sind unveränderlich, sobald die Orchestrierung, Aktivität oder Unterorchestrierung eingeplant wurde.
• Tagschlüssel und -werte sind Zeichenfolgen.
• Man kann Aktivitätstags im Orchestrierungsverlauf überprüfen, aber nicht abfragen. Man kann sie auch nicht an Aktivitätsfunktionen weiterleiten.

Nächste Schritte

• Entwickeln mit dauerhaftem Aufgabenplaner
• Automatisches Löschen von Orchestrierungsdaten
• Orchestrierungsverlauf exportieren