Unterstützung großer Nutzlasten mit Durable Task Scheduler (Vorschau)

Die Unterstützung für große Nutzlasten ermöglicht es Ihrer App, Orchestrierungseingaben und Aktivitätsergebnisse zu übergeben, die die Nachrichtengrößenbegrenzung des Durable Task Scheduler überschreiten. Wenn eine Nutzlast den konfigurierten Schwellenwert überschreitet, speichert das Framework die serialisierte Nutzlast in Azure Blob Storage und sendet einen kleinen Verweis über den permanenten Aufgabenplaner.

Dieses Feature ist verfügbar für:

Durable Functions mit dem .NET-Worker im isolierten Modus
.NET Durable Task SDK
Python Durable Task SDK

Wenn Ihr Workflow Daten in Blob Storage speichert und nur einen URI oder einen Bezeichner übergibt, verwenden Sie dieses Muster weiterhin. Verwenden Sie die Unterstützung großer Nutzlasten, wenn Ihre Orchestrierungslogik die Nutzlast zwischen persistenten Vorgängen übergeben muss. Allgemeine Anleitungen finden Sie unter Datenpersistenz und Serialisierung in Durable Functions.

Unterstützte Frameworks

Diese Tabelle zeigt die Unterstützung großer Nutzlasten nach Framework.

Rahmenwerk	Status der Unterstützung	Was Sie benötigen
Durable Functions	Unterstützt in .NET isoliertem C#	Verwenden Sie den Durable Task Scheduler als Speicheranbieter und verwenden Sie `AzureWebJobsStorage` für Nutzlast-Blobs.
Robuste Aufgaben-SDKs	Unterstützt in .NET und Python	Verwenden der sprachspezifischen Azure Blob-Nutzlasterweiterung mit Azure Blob Storage
JavaScript, PowerShell und Java	Nicht verfügbar	Externen Speicher verwenden und Verweise zwischen dauerhaften Vorgängen übergeben

So funktioniert es

Wenn Sie die Unterstützung für große Nutzlasten aktivieren, folgt die Laufzeit in beiden Hostingmodellen dem gleichen allgemeinen Fluss:

Serialisiert die Orchestrierungseingabe oder Aktivitätsausgabe.
Wenn die Nutzlastgröße ihren konfigurierten Schwellenwert überschreitet, komprimiert die Laufzeit die Nutzlast mit gzip.
Sie schreibt die komprimierte Nutzlast in Azure Blob Storage.
Sendet anstelle der vollständigen Nutzlast einen Blob-Verweis über den Durable Task Scheduler.
Die Laufzeit löst den Verweis automatisch auf, bevor Ihr Orchestrator- oder Aktivitätscode den Wert liest.

Die aktuellen .NET-Beispiele verwenden deterministische, gering komprimierbare 1,5 MiB Nutzlasten. Dadurch bleibt die gespeicherte BLOB-Größe repräsentativ, obwohl die Laufzeit Blobs mit gzip-Inhaltscodierung schreibt.

Die Unterstützung großer Nutzlasten verändert die Art und Weise, wie sich die Nutzlasten während der Laufzeit bewegen. Sie verändert nicht die Empfehlung, den dauerhaften Zustand so klein wie möglich zu halten.

Auswählen des richtigen Musters

Verwenden Sie das einfachste Muster für Ihr Szenario.

Verwenden Sie dieses Muster.	Wann man es verwenden sollte
Unterstützung großer Nutzlast	Die Orchestrierung übergibt die Nutzlast zwischen dauerhaften Vorgängen, und die Nutzlast überschreitet das Nachrichtenlimit des Schedulers.
Externer Speicher plus Verweise	Ihre Aktivitäten laden Daten direkt aus dem Speicher, und Sie möchten den kleinstmöglichen Orchestrierungszustand.

Aktivieren der Unterstützung großer Nutzlast

Unterstützung großer Nutzlasten in Durable Functions ist nur für .NET isolierte C#-Anwendungen verfügbar, die den Durable Task Scheduler als Speicheranbieter verwenden.

Bevor Sie das Feature aktivieren, stellen Sie sicher, dass Ihre App:

Verwendet den isolierten .NET Worker.
Verweist auf Microsoft.Azure.Functions.Worker.Extensions.DurableTask und Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged.
Legt diesen AzureWebJobsStorage Wert auf das Speicherkonto fest, das externe Nutzlasten enthält.
Legt DTS_CONNECTION_STRING und TASKHUB_NAME für den Zielplaner und den Aufgabenhub fest.

Aktivieren Sie dann großen Nutzlastspeicher in host.json:

{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "storageProvider": {
        "type": "azureManaged",
        "connectionStringName": "DTS_CONNECTION_STRING",
        "payloadStorageEnabled": true,
        "payloadStorageThresholdBytes": 900000
      },
      "hubName": "%TASKHUB_NAME%"
    }
  }
}

Legen Sie payloadStorageThresholdBytes so fest, dass es unter dem Grenzwert für die Nachrichtengröße des Durable Task Schedulers liegt, sodass die Laufzeit die Nutzlasten externalisiert, bevor sie sich dem Grenzwert nähern.

Verwenden Sie die standard-Durable Functions-APIs in Ihrem Orchestrator- und Aktivitätscode. Die Laufzeit löst blob-Verweise automatisch auf, bevor context.GetInput<T>() und context.CallActivityAsync<T>() Daten zurückgeben.

Standardmäßig schreibt die Erweiterung externe Nutzlasten in den durabletask-payloads Container im durch AzureWebJobsStorage konfigurierten Speicherkonto.

End-to-End-Beispiele finden Sie in den folgenden Beispielen:

Die Unterstützung großer Nutzlasten in den SDKs für dauerhafte Aufgaben ist für .NET- und Python-Apps verfügbar.

Installieren Sie das Azure Blob-Nutzlasterweiterungspaket:

dotnet add package Microsoft.DurableTask.Extensions.AzureBlobPayloads

Installieren Sie die verwalteten Client- und Arbeitspakete von Azure für den Durable Task Scheduler.

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

Registrieren Sie einen externen Nutzlastspeicher, wählen Sie einen Schwellenwert aus, und aktivieren Sie die Nutzlastauflösung sowohl auf dem Client als auch auf dem Worker:

builder.Services.AddExternalizedPayloadStore(options =>
{
    options.ThresholdBytes = 900_000;
    options.ConnectionString = builder.Configuration["PAYLOAD_STORAGE_CONNECTION_STRING"]
        ?? "UseDevelopmentStorage=true";
    options.ContainerName = "durabletask-payloads";
});

builder.Services.AddDurableTaskClient(client =>
{
    client.UseDurableTaskScheduler(schedulerConnectionString);
    client.UseExternalizedPayloads();
});

builder.Services.AddDurableTaskWorker(worker =>
{
    worker.UseDurableTaskScheduler(schedulerConnectionString);
    worker.UseExternalizedPayloads();
});

Wenn Sie Microsoft Entra ID anstelle einer Speicher-Verbindungszeichenfolge verwenden, legen Sie options.AccountUri und options.Credential fest. Das Beispiel verwendet DefaultAzureCredential und kann optional auf eine vom Benutzer zugewiesene verwaltete Identität abzielen.

Legen Sie ThresholdBytes auf 1,048,576 Byte oder auf einen niedrigeren Wert fest. Im Beispiel werden 900,000 Bytes verwendet, sodass die Nutzlasten entladen werden, bevor sie sich dem 1 MiB-Nachrichtenlimit des Schedulers nähern.

Ein End-to-End-.NET Beispiel finden Sie im Beispiel Durable Task SDK– Beispiel für große Nutzlast.

Installieren Sie das Python SDK mit der Azure Blob-Nutzlasterweiterung und dem Azure verwalteten Transportpaket:

pip install durabletask[azure-blob-payloads] durabletask-azuremanaged

Erstellen Sie einen BlobPayloadStore, wählen Sie einen Schwellenwert aus, und übergeben Sie denselben Speicher sowohl an den Worker als auch an den Client:

from durabletask.azuremanaged.client import DurableTaskSchedulerClient
from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker
from durabletask.extensions.azure_blob_payloads import BlobPayloadStore, BlobPayloadStoreOptions

store = BlobPayloadStore(BlobPayloadStoreOptions(
    connection_string=storage_connection_string,
    container_name="durabletask-payloads",
    threshold_bytes=900_000,
))

with DurableTaskSchedulerWorker(
    host_address=endpoint,
    secure_channel=secure_channel,
    taskhub=taskhub_name,
    token_credential=credential,
    payload_store=store,
) as worker:
    worker.start()

    client = DurableTaskSchedulerClient(
        host_address=endpoint,
        secure_channel=secure_channel,
        taskhub=taskhub_name,
        token_credential=credential,
        payload_store=store,
    )

Wenn Sie Microsoft Entra ID anstelle einer Speicherverbindungszeichenfolge verwenden, legen Sie account_url und credential in BlobPayloadStoreOptions fest. Das Beispiel verwendet DefaultAzureCredential.

Legen Sie threshold_bytes auf 1,048,576 Byte oder auf einen niedrigeren Wert fest. Das aktuelle Beispiel verwendet 1,024 Bytes, sodass Sie sehen können, wie die Nutzlast-Externalisierung während einer lokalen Ausführung erfolgt.

Für ein Beispiel für ein End-to-End-Python-Szenario, siehe das Durable Task SDK-Beispiel für große Nutzlast in Python.

Umgebungsvariablenkonfiguration

Verwenden Sie diese lokalen Einstellungen oder App-Einstellungen mit den aktuellen Durable Functions Beispielen.

Setting	Beschreibung	Beispiel Standard
`FUNCTIONS_WORKER_RUNTIME`	Azure Functions isolierter Worker-Runtime	`dotnet-isolated`
`AzureWebJobsStorage`	Speicher für den Hoststatus von Funktionen und Nutzlast-Blobs	`UseDevelopmentStorage=true` lokal
`DTS_CONNECTION_STRING`	Durable-Task-Planer-Verbindungszeichenfolge	`Endpoint=http://localhost:8080;Authentication=None`
`TASKHUB_NAME`	Zielaufgabenhub	`default`
`PAYLOAD_SIZE_BYTES`	Nutzlastgröße, die vom Starter verwendet oder von jeder Aktivität generiert wird	`1572864`
`ACTIVITY_COUNT`	Anzahl der parallelen Aktivitäten nur im Beispiel „Fan-Out/Fan-In“	`3`

Die ACTIVITY_COUNT Einstellung wird nur vom LargePayloadFanOutFanIn Beispiel verwendet. Wird vom LargePayload-Roundtrip-Muster nicht gelesen.

Verwenden Sie diese Umgebungsvariablen mit den aktuellen Beispielen für das Durable Task SDK.

Variable	Beschreibung	Beispiel Standard
`DURABLE_TASK_SCHEDULER_CONNECTION_STRING`	Durable-Task-Planer-Verbindungszeichenfolge	`Endpoint=http://localhost:8080;TaskHub=default;Authentication=None`
`PAYLOAD_STORAGE_CONNECTION_STRING`	Blob-Speicher-Verbindungszeichenfolge für externe Nutzlasten	`UseDevelopmentStorage=true`
`PAYLOAD_STORAGE_ACCOUNT_URI`	BLOB-Konto-URI für identitätsbasierten Nutzlastspeicherzugriff	Nicht festgelegt
`PAYLOAD_CONTAINER_NAME`	BLOB-Container für externisierte Nutzlasten	`durabletask-payloads`
`PAYLOAD_SIZE_BYTES`	Standardnutzlastgröße, die vom Ausführungsendpunkt verwendet wird	`1572864`
`EXTERNALIZE_THRESHOLD_BYTES`	Blob-Offloadschwellenwert	`900000`
`PAYLOAD_STORAGE_MANAGED_IDENTITY_CLIENT_ID`	Optionale vom Benutzer zugewiesene Client-ID für verwaltete Identität für den Speicherzugriff	Nicht festgelegt
`AZURE_CLIENT_ID`	Alternative Möglichkeit zum Auswählen einer vom Benutzer zugewiesenen verwalteten Identität	Nicht festgelegt
`ASPNETCORE_URLS`	Lauschen für den HTTP-Host des Beispiels	Framework Standard

Wenn PAYLOAD_STORAGE_CONNECTION_STRING nicht festgelegt und PAYLOAD_STORAGE_ACCOUNT_URI bereitgestellt wird, verwendet das Beispiel DefaultAzureCredential. Wenn Sie eine bestimmte vom Benutzer zugewiesene Identität benötigen, legen Sie diese fest PAYLOAD_STORAGE_MANAGED_IDENTITY_CLIENT_ID oder AZURE_CLIENT_ID.

Variable	Beschreibung	Beispiel Standard
`ENDPOINT`	Dauerhafter Aufgabenplanungsendpunkt	`http://localhost:8080`
`TASKHUB`	Zielaufgabenhub	`default`
`STORAGE_CONNECTION_STRING`	Blob-Speicher-Verbindungszeichenfolge für externe Nutzlasten	`UseDevelopmentStorage=true`

Im Python Beispiel wird threshold_bytes im Code mit BlobPayloadStoreOptions festgelegt.

Azure-Berechtigungen

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

Erteilen Sie Durable Task Data Contributor auf dem Aufgabenhub der App.
Gewähren Sie Storage Blob Data Contributor Zugriff auf das Speicherkonto, das Nutzlast-BLOBs speichert.

Diese Berechtigungen gelten für Durable Functions Apps und durable Task SDK-Apps, die eine verwaltete Identität verwenden.

Überprüfen, ob das Entladen der Nutzlast funktioniert

Nachdem Sie das Entladen der Nutzlast aktiviert haben, führen Sie eine Orchestrierung mit einer Eingabe oder Ausgabe aus, die größer als der konfigurierte Schwellenwert ist. Überprüfen Sie dann auf beide Signale:

Die Orchestrierung wird erfolgreich abgeschlossen, selbst wenn die Nutzlast 1 MiB überschreitet.
Blob-Einträge werden im durabletask-payloads Container angezeigt.

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 durabletask-payloads \
  --output table

Die Beispiel-Apps validieren auch den Roundtrip.

Die Durable Functions Beispiele geben ein kleines Zusammenfassungsobjekt zurück, das die Eingabe- und Ausgabegrößen bestätigt.
Im Beispiel für das .NET Durable Task SDK wird angezeigt, ob bei der Ausführung neue Nutzlast-Blobs erstellt werden.
Das Beispiel für das Python Durable Task SDK führt sowohl Inline- als auch externe Nutzlastflüsse aus und druckt das Orchestrierungsergebnis für jede Ausführung.

Da die Laufzeit externe Nutzlasten mit Gzip-Inhaltscodierung speichert, meldet Azure die komprimierte Blob-Größe im Speicher. Bei den aktuellen Beispielnutzlasten mit geringer Komprimierbarkeit sollten diese Blobgrößen relativ nahe an der logischen Nutzlastgröße bleiben.

Hinweis

Das Löschen von Orchestrierungsinstanzen löscht derzeit nicht die entsprechenden externalisierten Nutzlast-Blobs aus Azure Blob Storage. Wenn Sie diese Payloads entfernen müssen, löschen Sie die BLOBs aus dem Speicherkonto separat.

Nächste Schritte

Configure Durable Functions mit Durable Task Scheduler

Erstellen einer App mit den SDKs für dauerhafte Aufgaben

Feedback

War diese Seite hilfreich?

Last updated on 2026-04-14