Exportieren des Orchestrierungsverlaufs mit Durable Task Scheduler (Vorschau)

Mit dem Feature zum Exportieren des Orchestrierungsverlaufs kann Ihre App Ausführungshistorien für Terminal-Orchestrierungsinstanzen (abgeschlossen, fehlgeschlagen oder beendeter Status) aus Durable Task Scheduler extrahieren und in Azure Blob Storage schreiben. Verwenden Sie dieses Feature zur Überwachung, Compliance, Analyse und langfristigen Archivierung von Orchestrierungsdaten außerhalb des Zeitplans.

Wie der Export der Orchestrierungshistorie funktioniert

Der Exportverlauf verwendet intern dauerhafte Entitäten und Orchestrierungen, um Exportaufträge zuverlässig gemäß dem folgenden Prozess zu verwalten.

1. Sie erstellen einen Exportauftrag über das ExportHistoryClient, indem Sie ein Zeitfenster und einen Exportmodus angeben.
2. Das SDK erstellt eine dauerhafte Entität (ExportJob), die den Status und den Fortschritt des Auftrags nachverfolgt.
3. Eine interne Orchestrierung listet Terminal-Orchestrierungsinstanzen auf, die mit den angegebenen Zeitfenster- und Statusfiltern übereinstimmen.
4. Für jede übereinstimmende Instanz ruft eine Aktivität den vollständigen Ausführungsverlauf von Durable Task Scheduler ab.
5. Der Verlauf wird serialisiert (JSONL mit standardmäßiger Gzip-Komprimierung) und in Azure Blob Storage geschrieben.
6. Der Auftrag kontrolliert seinen Fortschritt selbst, sodass er bei Unterbrechungen fortgesetzt werden kann.

Exportmodi für Batch- und fortlaufende Aufträge

Der Exportverlauf unterstützt zwei Modi:

Voraussetzungen

• .NET 8 SDK oder höher
• Ein Taskhub für dauerhafte Aufgabenplanung (oder der lokale Emulator)
• Ein Azure Storage Konto (oder Azurite für die lokale Entwicklung)
• Die folgenden NuGet-Pakete:
  • Microsoft.DurableTask.ExportHistory
  • Microsoft.DurableTask.Client.AzureManaged
  • Microsoft.DurableTask.Worker.AzureManaged

Aktivieren Sie den Export des Orchestrierungsverlaufs

1. Installieren Sie das Exportverlaufspaket.

   dotnet add package Microsoft.DurableTask.ExportHistory
   

2. Installieren Sie die Azure-verwalterten Client- und Worker-Pakete für den Durable Task Scheduler.

   dotnet add package Microsoft.DurableTask.Client.AzureManaged
   dotnet add package Microsoft.DurableTask.Worker.AzureManaged
   

3. Registrieren des Exportverlaufs sowohl für den Worker als auch für den Client.

   using Microsoft.DurableTask.Client;
   using Microsoft.DurableTask.Client.AzureManaged;
   using Microsoft.DurableTask.ExportHistory;
   using Microsoft.DurableTask.Worker;
   using Microsoft.DurableTask.Worker.AzureManaged;
   
   string connectionString = builder.Configuration.GetValue<string>("DURABLE_TASK_CONNECTION_STRING")
       ?? throw new InvalidOperationException("Missing DURABLE_TASK_CONNECTION_STRING");
   
   string storageConnectionString = builder.Configuration.GetValue<string>("EXPORT_HISTORY_STORAGE_CONNECTION_STRING")
       ?? throw new InvalidOperationException("Missing EXPORT_HISTORY_STORAGE_CONNECTION_STRING");
   
   string containerName = builder.Configuration.GetValue<string>("EXPORT_HISTORY_CONTAINER_NAME")
       ?? throw new InvalidOperationException("Missing EXPORT_HISTORY_CONTAINER_NAME");
   
   // Register the worker with export history support.
   // This registers internal entities, orchestrations, and activities that manage export jobs.
   builder.Services.AddDurableTaskWorker(worker =>
   {
       worker.UseDurableTaskScheduler(connectionString);
       worker.UseExportHistory();
   });
   
   // Register the client with export history support.
   // This configures the Azure Blob Storage destination and registers the ExportHistoryClient.
   builder.Services.AddDurableTaskClient(client =>
   {
       client.UseDurableTaskScheduler(connectionString);
       client.UseExportHistory(options =>
       {
           options.ConnectionString = storageConnectionString;
           options.ContainerName = containerName;
   
           // Optional: set a virtual folder path prefix for blob names (for example, "exports/daily").
           // When set, blobs are written to "{prefix}/{hash}.{ext}" instead of "{hash}.{ext}".
           options.Prefix = builder.Configuration.GetValue<string>("EXPORT_HISTORY_PREFIX");
       });
   });
   

Erstellen und Verwalten von Exportaufträgen

Nachdem Sie den Exportverlauf aktiviert haben, verwenden Sie die ExportHistoryClient Option zum Erstellen und Verwalten von Aufträgen.

Erstellen eines Batchexportauftrags

Im folgenden Beispiel exportiert ein Batch-Exportauftrag alle Orchestrierungsinstanzen, die innerhalb eines festgelegten Zeitfensters einen Endzustand erreicht haben.

ExportHistoryClient exportClient = app.Services.GetRequiredService<ExportHistoryClient>();

ExportJobCreationOptions options = new(
    mode: ExportMode.Batch,
    completedTimeFrom: DateTimeOffset.UtcNow.AddHours(-24),
    completedTimeTo: DateTimeOffset.UtcNow,
    destination: new ExportDestination("my-export-container")
    {
        // Virtual folder path prefix applied to all blob names for this job
        Prefix = "exports/daily",
    });

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);
ExportJobDescription description = await jobClient.DescribeAsync();

Erstellen eines fortlaufenden Exportauftrags

Im folgenden Beispiel überwacht ein kontinuierlicher Exportauftrag Terminalinstanzen auf unbegrenzte Zeit ab einem Startzeitpunkt.

ExportJobCreationOptions options = new(
    mode: ExportMode.Continuous,
    completedTimeFrom: DateTimeOffset.UtcNow,
    completedTimeTo: null,
    destination: null);

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);

Wenn destination null ist, verwendet der Job den Standardcontainer und das in ExportHistoryStorageOptions konfigurierte Präfix.

Abrufen von Exportauftragsdetails

Verwenden Sie den folgenden Code, um die vollständige Beschreibung eines Auftrags abzurufen, einschließlich seines Status, Fortschrittszählern und aller Fehler.

ExportJobDescription? job = await exportClient.GetJobAsync("my-job-id");

Der ExportJobDescription umfasst:

Aufträge auflisten

Exportieren Sie eine Liste der aktiven Aufträge mithilfe von Code, der dem folgenden Beispiel ähnelt.

ExportJobQuery query = new()
{
    Status = ExportJobStatus.Active,
    CreatedFrom = DateTimeOffset.UtcNow.AddDays(-7),
    PageSize = 50,
};

AsyncPageable<ExportJobDescription> jobs = exportClient.ListJobsAsync(query);

await foreach (ExportJobDescription job in jobs)
{
    Console.WriteLine($"{job.JobId}: {job.Status} ({job.ExportedInstances} exported)");
}

Die ExportJobQuery unterstützt die folgenden Filtereigenschaften:

Löschen eines Auftrags

Verwenden Sie den folgenden Code, um einen Auftrag zu löschen.

ExportHistoryJobClient jobClient = exportClient.GetJobClient("my-job-id");
await jobClient.DeleteAsync();

Exportauftragserstellungsoptionen

Die ExportJobCreationOptions Klasse steuert das Exportauftragsverhalten und enthält die folgenden Parameter.

Wo exportierte Daten in Azure Blob Storage gespeichert werden

Der exportierte Verlauf wird mit den folgenden Parametern in Azure Blob Storage geschrieben.

• Container: Standardeinstellung von EXPORT_HISTORY_CONTAINER_NAME oder auftragsspezifische destination-Überschreibung.
• Blobname: abgeleitet von einem SHA-256-Hash von (completedTimestamp, instanceId).
• Dateiformat:
  • Standard: .jsonl.gz (JSON-Zeilen, gzip-komprimiert – ein Verlaufsereignis pro Zeile)
  • Optional: .json (nicht komprimiertes JSON-Array von Verlaufsereignissen)
• Blobpfad mit Präfix: Wenn ein Präfix konfiguriert ist (z. B. exports/daily), wird der Blobpfad zu exports/daily/{hash}.{ext}. Ohne Präfix wird das Blob direkt in den Containerstamm geschrieben als {hash}.{ext}.

Jedes Blob enthält ein instanceId Metadatentag zur Rückverfolgbarkeit.

Umgebungsvariablen für die Konfiguration des Exportverlaufs

Verwenden Sie diese Umgebungsvariablen mit dem Durable Task .NET SDK Exportverlauf-Beispiel.

Azure Berechtigungen für den Exportverlauf

Wenn Sie Azure Ressourcen anstelle lokaler Emulatoren verwenden, benötigt die App-Identität Zugriff auf den Dauerhaften Aufgabenplaner und Blob Storage:

1. Erteilen Sie Durable Task Data Contributor auf dem Aufgabenhub der App.
2. Storage Blob Data Contributor-Berechtigungen für das Speicherkonto gewähren, unter dem exportierte Verlaufsblobs gespeichert werden.

Wichtige Überlegungen für Exportaufträge

• Gleichzeitige Bereinigungsvorgänge:
  Wenn Sie Orchestrierungsinstanzen löschen, während ein Exportauftrag ausgeführt wird, kann dies Auswirkungen auf den Export haben. Instanzen, die gelöscht wurden, bevor sie vom Exportauftrag gelesen wurden, fehlen in den exportierten Daten. Vermeiden Sie gleichzeitiges Ausführen von Bereinigungsvorgängen mit aktiven Exportaufträgen, die das gleiche Zeitfenster abdecken.

• Blobbereinigung:
  Beim Löschen eines Exportauftrags werden die exportierten Blobs nicht aus Azure Blob Storage entfernt. Wenn Sie exportierte Daten entfernen müssen, löschen Sie die BLOBs separat aus dem Speicherkonto.

Überprüfen, ob der Export funktioniert

Nachdem Sie einen Exportauftrag erstellt haben, überprüfen Sie ihn, indem Sie nach beiden Signalen suchen:

• Der Auftragsstatus wechselt von Pending zu Active und schließlich zu Completed (für den Batchmodus).
• Blob-Einträge werden im konfigurierten Exportcontainer angezeigt.

Sie können den Auftragsstatus programmgesteuert abfragen:

ExportJobDescription? job;
do
{
    await Task.Delay(TimeSpan.FromSeconds(5));
    job = await exportClient.GetJobAsync(jobId);
    Console.WriteLine($"Status: {job?.Status}, Exported: {job?.ExportedInstances}");
}
while (job?.Status is ExportJobStatus.Pending or ExportJobStatus.Active);

Führen Sie für die lokale Entwicklung diesen Azure CLI Befehl aus, um den Container zu prüfen:

az storage blob list \
  --connection-string "UseDevelopmentStorage=true" \
  --container-name export-history \
  --output table

Nächste Schritte

• Durable Task .NET SDK-Exportverlaufsbeispiel
• Erstellen einer App mit den SDKs für dauerhafte Aufgaben