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 nur für C#-Apps verfügbar:

Dauerhafte Funktionen mit dem isolierten .NET-Worker
.NET 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 dauerhaften Funktionen.

Unterstützte Frameworks

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

Rahmen	Status der Unterstützung	Was Sie benötigen
Durable Functions	Unterstützt in isolierten .NET C#	Verwenden Sie den Durable Task Scheduler als Speicheranbieter und verwenden Sie `AzureWebJobsStorage` für Nutzlast-Blobs.
Robuste Aufgaben-SDKs	Unterstützt in .NET	Nutzen Sie `Microsoft.DurableTask.Extensions.AzureBlobPayloads` mit Azure Blob Storage
JavaScript, Python, 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.

In den aktuellen .NET-Beispielen werden deterministische Nutzlasten mit geringer Komprimierbarkeit und einer Größe von 1,5 MiB verwendet. 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

Die Unterstützung großer Nutzlasten in dauerhaften Funktionen ist nur für .NET isolierte C#-Apps 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.
Verweise 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",
        "largePayloadStorageEnabled": true,
        "largePayloadStorageThresholdBytes": 900000
      },
      "hubName": "%TASKHUB_NAME%"
    }
  }
}

Legen Sie largePayloadStorageThresholdBytes 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-APIs für dauerhafte Funktionen 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 nur für .NET-Apps verfügbar.

Installieren Sie das Azure Blob Payload-Erweiterungspaket:

dotnet add package Microsoft.DurableTask.Extensions.AzureBlobPayloads

Installieren Sie die Azure Managed-Client- und Workerpakete für den dauerhaften Aufgabenplaner:

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.ExternalizeThresholdBytes = 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 Speicherverbindungszeichenfolge 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 ExternalizeThresholdBytes 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 für das Durable Task SDK für große Nutzlasten.

Umgebungsvariablenkonfiguration

Verwenden Sie diese lokalen Einstellungen oder App-Einstellungen mit den aktuellen Beispielen für dauerhafte Funktionen.

Setting	Beschreibung	Beispiel Standard
`FUNCTIONS_WORKER_RUNTIME`	Isolierte Workerlaufzeit von Azure Functions	`dotnet-isolated`
`AzureWebJobsStorage`	Speicher für den Hoststatus von Funktionen und Nutzlast-Blobs	`UseDevelopmentStorage=true` lokal
`DTS_CONNECTION_STRING`	Verbindungszeichenfolge für Durable Task Scheduler	`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 dem aktuellen .NET Durable Task SDK-Beispiel.

Variable	Beschreibung	Beispiel Standard
`DURABLE_TASK_SCHEDULER_CONNECTION_STRING`	Verbindungszeichenfolge für Durable Task Scheduler	`Endpoint=http://localhost:8080;TaskHub=default;Authentication=None`
`PAYLOAD_STORAGE_CONNECTION_STRING`	Blob-Speicher-Verbindungszeichenfolge für externalisierte Datenlasten	`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.

Azure-Berechtigungen

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

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 Beispiele für dauerhafte Funktionen geben ein kleines Zusammenfassungsobjekt zurück, das die Eingabe- und Ausgabegrößen bestätigt.
Im Beispiel für das .NET Durable Task SDK wird gedruckt, ob die Ausführung neue Nutzlast-Blobs erstellt.

Da die Laufzeit externe Nutzlasten mit gzip-Inhaltscodierung speichert, meldet Azure die komprimierte Größe des Datenträger-Blobs. 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 externen 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

Konfigurieren dauerhafter Funktionen mit dauerhaftem Aufgabenplaner

Erstellen einer App mit den SDKs für dauerhafte Aufgaben

Feedback

War diese Seite hilfreich?

Last updated on 2026-03-25