Eksportowanie historii aranżacji za pomocą narzędzia Durable Task Scheduler (wersja zapoznawcza)

Funkcja eksportowania historii orkiestracji umożliwia aplikacji wyodrębnianie historii wykonywania dla końcowych instancji orkiestracji (ukończonych, nieudanych lub zakończonych) z Durable Task Scheduler i zapisuje je w Azure Blob Storage. Ta funkcja służy do inspekcji, zgodności, analizy i długoterminowego archiwizowania danych aranżacji poza harmonogramem.

Jak działa eksportowanie historii aranżacji

Historia eksportu używa trwałych jednostek i orkiestracji wewnętrznie do niezawodnego zarządzania zadaniami eksportu według następującego procesu.

1. Tworzysz zadanie eksportu za pomocą ExportHistoryClient, określając przedział czasu i tryb eksportu.
2. Zestaw SDK tworzy trwałą jednostkę (ExportJob), która śledzi stan i postęp zadania.
3. Wewnętrzna aranżacja wyświetla wystąpienia orkiestracji terminalu, które pasują do określonego przedziału czasu i filtrów stanu.
4. Dla każdego pasującego wystąpienia działanie pobiera pełną historię wykonywania z narzędzia Durable Task Scheduler.
5. Historia jest serializowana (JSONL z kompresją gzip domyślnie) i zapisywana w Azure Blob Storage.
6. Zadanie zapisuje swój postęp, aby można było wznowić proces, jeśli zostanie przerwany.

Typy eksportu dla zadań wsadowych i ciągłych

Historia eksportu obsługuje dwa tryby:

Wymagania wstępne

• .NET 8 SDK lub nowszy
• Trwały Durable Task Scheduler hub zadań (lub emulator lokalny)
• Konto Azure Storage (lub Azurite na potrzeby programowania lokalnego)
• Następujące pakiety NuGet:
  • Microsoft.DurableTask.ExportHistory
  • Microsoft.DurableTask.Client.AzureManaged
  • Microsoft.DurableTask.Worker.AzureManaged

Włączanie eksportowania historii aranżacji

1. Zainstaluj pakiet historii eksportu.

   dotnet add package Microsoft.DurableTask.ExportHistory
   

2. Zainstaluj pakiety klienta i procesu roboczego zarządzanego Azure dla harmonogramu zadań Durable Task Scheduler.

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

3. Zarejestruj historię eksportu zarówno w procesie roboczym, jak i u klienta.

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

Tworzenie zadań eksportu i zarządzanie nimi

Po włączeniu historii eksportu użyj polecenia ExportHistoryClient , aby utworzyć zadania i zarządzać nimi.

Utwórz zadanie eksportu wsadowego

W poniższym przykładzie zadanie wsadowe eksportuje wszystkie wystąpienia orkiestracji, które osiągnęły stan końcowy w określonym przedziale czasu.

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

Utwórz zadanie eksportu ciągłego

W poniższym przykładzie ciągłe zadanie eksportu śledzi wystąpienia terminalu na czas nieokreślony od czasu rozpoczęcia.

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

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);

Gdy destination ma wartość null, zadanie używa domyślnego kontenera i prefiksu skonfigurowanego w ExportHistoryStorageOptions.

Uzyskaj szczegóły zadania eksportu

Użyj poniższego kodu, aby pobrać pełny opis zadania, w tym jego stan, liczniki postępu i wszelkie błędy.

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

Obejmuje ExportJobDescription :

Wyświetlanie listy zadań

Wyeksportuj listę aktywnych zadań przy użyciu kodu podobnego do poniższego przykładu.

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

Element ExportJobQuery obsługuje następujące właściwości filtru:

Usuwanie zadania

Użyj następującego kodu, aby usunąć zadanie.

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

Opcje tworzenia zadania eksportu

Klasa ExportJobCreationOptions steruje zachowaniem zadania eksportu i zawiera następujące parametry.

Gdzie eksportowane dane są przechowywane w Azure Blob Storage

Wyeksportowana historia jest zapisywana w Azure Blob Storage przy użyciu następujących parametrów.

• Kontener: domyślnie z EXPORT_HISTORY_CONTAINER_NAME, lub zastąpienie dla poszczególnych zadań destination.
• Nazwa obiektu blob: pochodzi ze skrótu SHA-256 zasobu (completedTimestamp, instanceId).
• Format pliku:
  • Ustawienie domyślne: .jsonl.gz (Linie JSON, skompresowane za pomocą pliku gzip — jedno zdarzenie historii na wiersz)
  • Opcjonalnie: .json (nieskompresowana tablica zdarzeń historii JSON)
• Ścieżka obiektu blob z prefiksem: kiedy prefiks zostanie skonfigurowany (na przykład ), ścieżka obiektu blob staje się exports/daily. Bez prefiksu obiekt blob jest zapisywany bezpośrednio w root kontenera jako {hash}.{ext}.

Każdy obiekt blob zawiera instanceId tag metadanych umożliwiający śledzenie.

Zmienne środowiskowe konfiguracji historii eksportu

Użyj tych zmiennych środowiskowych z przykładem historii eksportu zestawu Durable Task .NET SDK.

Uprawnienia Azure do historii eksportu

Jeśli używasz zasobów Azure zamiast lokalnych emulatorów, identyfikator aplikacji musi mieć dostęp do Harmonogramu Zadań Durable Task i magazynu obiektów Blob:

1. Nadaj Durable Task Data Contributor w centrum zadań aplikacji.
2. Przyznaj Storage Blob Data Contributor na koncie magazynu przechowującym wyeksportowane obiekty blob historii.

Ważne zagadnienia dotyczące zadań eksportu

• Równoczesne operacje przeczyszczania:
  Jeśli usuwasz wystąpienia orkiestracji podczas, gdy zadanie eksportu jest uruchomione, może to mieć wpływ na eksport. Wystąpienia, które zostaną usunięte przed rozpoczęciem eksportu, nie pojawią się w wyeksportowanych danych. Unikaj uruchamiania operacji przeczyszczania jednocześnie z aktywnymi zadaniami eksportu, które obejmują to samo okno czasowe.

• Oczyszczanie blobów:
  Usunięcie zadania eksportu nie powoduje usunięcia wyeksportowanych obiektów blob z Azure Blob Storage. Jeśli musisz usunąć wyeksportowane dane, usuń bloby z konta przechowywania oddzielnie.

Sprawdzanie, czy eksport działa

Po utworzeniu zadania eksportu sprawdź, czy działa, sprawdzając oba sygnały:

• Stan zadania przechodzi z Pending do Active, a następnie ostatecznie do Completed (w trybie wsadowym).
• Wpisy obiektów blob są wyświetlane w skonfigurowanym kontenerze eksportu.

Można programowo monitorować status zadania:

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

W przypadku programowania lokalnego uruchom następujące polecenie Azure CLI, aby sprawdzić kontener:

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

Następne kroki

• Przykład eksportu historii z użyciem Durable Task .NET SDK
• Utwórz aplikację przy użyciu Durable Task SDK