Orchestrationgeschiedenis exporteren met Durable Task Scheduler (preview)

Met de exportfunctie voor indelingsgeschiedenis kunt u uitvoeringsgeschiedenissen voor terminalindelingsexemplaren (voltooide, mislukte of beëindigde status) extraheren uit Durable Task Scheduler en deze naar Azure Blob Storage schrijven. Gebruik deze functie voor controle, naleving, analyse en langetermijnarchivering van indelingsgegevens buiten de planner.

Hoe de orkestratiegeschiedenis wordt geëxporteerd

Exportgeschiedenis maakt intern gebruik van duurzame entiteiten en coördinaties om exporttaken betrouwbaar te beheren volgens het volgende proces.

1. U maakt een exporttaak via de ExportHistoryClient, waarbij u een tijdvenster en exportmodus opgeeft.
2. De SDK maakt een duurzame entiteit (ExportJob) die de status en voortgang van de taak bijhoudt.
3. Een interne indeling bevat terminalindelingsexemplaren die overeenkomen met het opgegeven tijdvenster en statusfilters.
4. Voor elk overeenkomend exemplaar haalt een activiteit de volledige uitvoeringsgeschiedenis van Durable Task Scheduler op.
5. De geschiedenis wordt standaard geserialiseerd (JSONL met gzip-compressie) en naar Azure Blob Storage geschreven.
6. De voortgang van de taak wordt gecontroleerd, zodat deze kan worden hervat als deze wordt onderbroken.

Modi voor export voor batch- en doorlopende taken

Exportgeschiedenis ondersteunt twee modi:

Vereiste voorwaarden

• .NET 8 SDK of hoger
• Een Durable Task Scheduler-taakhub (of de lokale emulator)
• Een Azure Storage-account (of Azurite voor lokale ontwikkeling)
• De volgende NuGet-pakketten:
  • Microsoft.DurableTask.ExportHistory
  • Microsoft.DurableTask.Client.AzureManaged
  • Microsoft.DurableTask.Worker.AzureManaged

Orchestration history export inschakelen

1. Installeer het exportgeschiedenispakket.

   dotnet add package Microsoft.DurableTask.ExportHistory
   

2. Installeer de Azure beheerde client- en werkpakketten voor Durable Task Scheduler.

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

3. Registreer de exportgeschiedenis op zowel de werker als de 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");
       });
   });
   

Exporttaken maken en beheren

Nadat u de exportgeschiedenis hebt ingeschakeld, gebruikt u ExportHistoryClient om taken te maken en beheren.

Een batchexporttaak maken

In het volgende voorbeeld exporteert een batch-exporttaak alle orkestratie-exemplaren die een terminale status binnen een vast tijdvenster hebben bereikt.

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

Een doorlopende exporttaak maken

In het volgende voorbeeld volgt een continue exporttaak terminalexemplaren onbepaalde tijd vanaf een begintijd.

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

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);

Wanneer destination is null, gebruikt de taak de standaardcontainer en het voorvoegsel dat is geconfigureerd in ExportHistoryStorageOptions.

Details van de exportopdracht ophalen

Gebruik de volgende code om de volledige beschrijving van een taak op te halen, inclusief de status, voortgangstellers en eventuele fouten.

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

De ExportJobDescription volgende omvat:

Opdrachten weergeven

Exporteer een lijst met actieve taken met behulp van code die vergelijkbaar is met het volgende voorbeeld.

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

De ExportJobQuery volgende filtereigenschappen worden ondersteund:

Een taak verwijderen

Gebruik de volgende code om een taak te verwijderen.

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

Opties voor het maken van een taak exporteren

De ExportJobCreationOptions klasse bepaalt het gedrag van de exporttaak en bevat de volgende parameters.

Waar geëxporteerde gegevens worden opgeslagen in Azure Blob Storage

Geëxporteerde geschiedenis wordt naar Azure Blob Storage geschreven met de volgende parameters.

• Container: standaard van EXPORT_HISTORY_CONTAINER_NAMEof de onderdrukking per taak destination .
• Blobnaam: afgeleid van een SHA-256-hash van (completedTimestamp, instanceId).
• Bestandsindeling:
  • Standaard: .jsonl.gz (JSON Lines, gzip-gecomprimeerd, één geschiedenisgebeurtenis per regel)
  • Optioneel: .json (niet-gecomprimeerde JSON-matrix met geschiedenisgebeurtenissen)
• Blobpad met voorvoegsel: wanneer een voorvoegsel is geconfigureerd (bijvoorbeeldexports/daily), wordt het blobpad .exports/daily/{hash}.{ext} Zonder voorvoegsel wordt de blob rechtstreeks naar de root van de container geschreven als {hash}.{ext}.

Elke blob bevat een instanceId metagegevenstag voor traceerbaarheid.

Omgevingsvariabelen voor configuratie van exportgeschiedenis

Gebruik deze omgevingsvariabelen met het voorbeeld van de durable task .NET SDK-exportgeschiedenis.

Azure machtigingen voor exportgeschiedenis

Wanneer u Azure resources gebruikt in plaats van lokale emulators, heeft de app-identiteit toegang nodig tot Durable Task Scheduler en Blob Storage:

1. Machtiging Durable Task Data Contributor aan de taakhub van de app verlenen.
2. Verleen Storage Blob Data Contributor toestemming voor het opslagaccount dat geëxporteerde geschiedenis-blobs opslaat.

Belangrijke overwegingen voor exporttaken

• Gelijktijdige opschoningsbewerkingen:
  Als u orkestratie-exemplaren opschoont terwijl een export wordt uitgevoerd, kan dit de export beïnvloeden. Exemplaren die worden opgeschoond voordat de export leest, ontbreken in de geëxporteerde gegevens. Vermijd het uitvoeren van opschoningsbewerkingen gelijktijdig met actieve exporttaken die hetzelfde tijdvenster behandelen.

• Blob-opschoning:
  Als u een exporttaak verwijdert, worden de geëxporteerde blobs niet uit Azure Blob Storage verwijderd. Als u geëxporteerde gegevens wilt verwijderen, verwijdert u de blobs afzonderlijk uit het opslagaccount.

Controleren of de export werkt

Nadat u een exporttaak hebt gemaakt, controleert u of deze werkt door te controleren op beide signalen:

• De taakstatus gaat over van Pending en Active naar Completed (voor batchmodus).
• Blob-vermeldingen worden weergegeven in de geconfigureerde exportcontainer.

U kunt de taakstatus programmatisch peilen:

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

Voer voor lokale ontwikkeling deze Azure CLI opdracht uit om de container te controleren:

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

Volgende stappen 

• Durable Task .NET SDK exportgeschiedenisvoorbeeld
• Een app maken met de Durable Task SDK's