Exportera orkestreringshistorik med Durable Task Scheduler (förhandsversion)

Med exportfunktionen för orkestreringshistorik kan appen extrahera körningshistorik för terminalorkestreringsinstanser (slutförd, misslyckad eller avslutad status) från Durable Task Scheduler och skriva dem till Azure Blob Storage. Använd den här funktionen för granskning, efterlevnad, analys och långsiktig arkivering av orkestreringsdata utanför schemaläggaren.

Så här fungerar export av orkestreringshistorik

Exporthistoriken använder varaktiga entiteter och orkestreringar internt för att hantera exportjobb på ett tillförlitligt sätt med följande process.

1. Du skapar ett exportjobb via ExportHistoryClient, anger ett tidsfönster och exportläge.
2. SDK:n skapar en varaktig entitet (ExportJob) som spårar jobbets tillstånd och förlopp.
3. En intern orkestrering visar en lista över terminalorkestreringsinstanser som matchar det angivna tidsfönstret och statusfilter.
4. För varje matchande instans hämtar en aktivitet den fullständiga körningshistoriken från Durable Task Scheduler.
5. Historiken serialiseras (JSONL med gzip-komprimering som standard) och skrivs till Azure Blob Storage.
6. Jobbet kontrollerar sina framsteg så att det kan återupptas om det avbryts.

Exportlägen för batch- och kontinuerliga jobb

Exporthistorik stöder två lägen:

Förutsättningar

• .NET 8 SDK eller senare
• En hållbar Task Scheduler-uppgiftshubb (eller lokal emulator)
• Ett Azure Storage-konto (eller Azurite för lokal utveckling)
• Följande NuGet-paket:
  • Microsoft.DurableTask.ExportHistory
  • Microsoft.DurableTask.Client.AzureManaged
  • Microsoft.DurableTask.Worker.AzureManaged

Aktivera export av orkestreringshistorik

1. Installera exporthistorikpaketet.

   dotnet add package Microsoft.DurableTask.ExportHistory
   

2. Installera Azure hanterade klient- och arbetspaketen för Durable Task Scheduler.

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

3. Registrera exporthistorik för både arbetaren och klienten.

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

Skapa och hantera exportjobb

När du har aktiverat exporthistoriken använder du ExportHistoryClient för att skapa och hantera jobb.

Skapa ett batchexportjobb

I följande exempel exporterar ett batchexportjobb alla orkestreringsinstanser som nått ett terminaltillstånd inom ett fast tidsfönster.

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

Skapa ett kontinuerligt exportjobb

I följande exempel följer ett kontinuerligt exportjobb terminaler oändligt från en starttidpunkt.

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

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);

När destination är null använder jobbet standardcontainern och prefixet som konfigurerats i ExportHistoryStorageOptions.

Hämta information om exportjobb

Använd följande kod för att hämta ett jobbs fullständiga beskrivning, inklusive dess status, förloppsräknare och eventuella fel.

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

Omfattar ExportJobDescription :

Lista arbeten

Exportera en lista över aktiva jobb med hjälp av kod som liknar följande exempel.

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

Stöder ExportJobQuery följande filteregenskaper:

Ta bort ett jobb

Använd följande kod för att ta bort ett jobb.

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

Alternativ för att skapa exportjobb

Klassen ExportJobCreationOptions styr exportjobbets beteende och innehåller följande parametrar.

Var exporterade data lagras i Azure Blob Storage

Exporterad historik skrivs till Azure Blob Storage med följande parametrar.

• Container: standard från EXPORT_HISTORY_CONTAINER_NAME, eller åsidosättning per jobb destination .
• Blobnamn: härledd från en SHA-256-hash av (completedTimestamp, instanceId).
• Filformat:
  • Förvalt: .jsonl.gz (JSON-rader, gzip-komprimerade – en historikhändelse per rad)
  • Valfritt: .json (okomprimerad JSON-matris med historikhändelser)
• Blobsökväg med prefix: när ett prefix har konfigurerats (till exempel exports/daily) blir exports/daily/{hash}.{ext}blobsökvägen . Utan ett prefix skrivs bloben direkt till containerroten som {hash}.{ext}.

Varje blob innehåller en instanceId metadatatagg för spårning.

Miljövariabler för konfiguration av exporthistorik

Använd dessa miljövariabler med Durable Task .NET SDK exporthistorikexempel.

Azure behörigheter för exporthistorik

När du använder Azure resurser i stället för lokala emulatorer behöver appidentiteten åtkomst till Durable Task Scheduler och Blob Storage:

1. Bevilja Durable Task Data Contributor på appens aktivitetshubb.
2. Bevilja Storage Blob Data Contributor för lagringskontot som lagrar exporterade historikblobar.

Viktiga överväganden för exportjobb

• Samtidiga rensningsåtgärder:
  Om du rensar orkestreringsinstanser medan ett exportjobb körs kan det påverka exporten. Instanser som rensas innan exporten läser dem kommer att saknas i de exporterade data. Undvik att köra rensningsåtgärder samtidigt med aktiva exportjobb som täcker samma tidsperiod.

• Rensning av blob:
  Om du tar bort ett exportjobb tas inte de exporterade blobarna bort från Azure Blob Storage. Om du behöver ta bort exporterade data tar du bort blobarna från lagringskontot separat.

Kontrollera att exporten fungerar

När du har skapat ett exportjobb kontrollerar du att det fungerar genom att söka efter båda signalerna:

• Jobbstatusen övergår från Pending till Active och till slut till Completed (för Batch-läge).
• Blobposter visas i den konfigurerade exportcontainern.

Du kan kontrollera jobbets status programmatiskt.

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ör lokal utveckling kör du det här Azure CLI kommandot för att inspektera containern:

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

Nästa steg

• Durable Task .NET SDK-exempel på exporthistorik
• Skapa en app med SDK:er för varaktiga uppgifter