System.Net.HttpClient: Download mit Resume – Range-Requests, ETag-Prüfung und saubere Partial-File-Strategie

Die Szene ist unerquicklich, aber typisch: Ein nächtlicher Job lädt ein großes Archiv, der Fortschrittsbalken steht bei 93 %. Dann ein kurzer VPN-Ruckler, Timeout, Abbruch. Am Morgen liegt eine Datei im Zielverzeichnis, Größe „passt“, aber beim Entpacken kommt nur noch „unexpected end of file“. Wer dann reflexartig „Resume“ nachrüstet, landet schnell beim nächsten Randfall: Der Download läuft durch, ist aber aus zwei Versionen zusammengesetzt.

Genau dafür ist ein HttpClient Download mit Resume gedacht – aber nur, wenn du ihn wie eine kleine Datenpipeline behandelst: mit klaren Regeln, wann du anhängen darfst, wie du Versionstreue prüfst (ETag/If-Range) und wie du lokale Zwischenstände (Partial Files) so verwaltest, dass Betrieb und Debugging nicht zum Ratespiel werden.

Der Zielkonflikt ist sauber benennbar: Bandbreite und Zeit sparen (Weiterladen statt Neustart) steht gegen Integrität und Wartbarkeit (kein stiller Versionsmix, nachvollziehbare Entscheidungen, reproduzierbares Fehlerbild). Dieser Beitrag ist als Abwägungskarte aufgebaut: Nutzen, Aufwand, Risiken, Grenzen – und eine pragmatische Linie, wann du Resume wirklich implementierst und wann ein guter Retry besser ist.

Abwägungskarte: Zwei Ziele, ein harter Trade-off

Resume lohnt sich nicht, weil es „modern“ ist, sondern weil dein Umfeld es erzwingt: große Dateien, instabile Leitungen, Zeitfenster im Batch, Nutzer, die Downloads abbrechen, oder Services, die nach Neustart dort weitermachen sollen, wo sie aufgehört haben. Gleichzeitig ist Resume die Stelle, an der man sich unbemerkt Datenkorruption einbaut – und die fällt oft erst viel später auf (Import schlägt fehl, Signatur ungültig, Setup lässt sich nicht ausführen).

Warum Resume mehr ist als „Range setzen“

HTTP kennt Byte-Range-Requests über den Range-Header. Der wichtige, oft übersehene Satz: Range-Unterstützung ist optional. Ein Server darf Range ignorieren und so antworten, als wäre es ein normaler GET – also mit 200 OK und vollem Body. Für Clients bedeutet das: Die Wahrheit steht in der Response, nicht in deiner Request-Absicht.^[Quelle]

Ein Resume-Client, der „Range geschickt“ mit „Teilinhalt kommt“ verwechselt, baut genau den Fehler, den du am Anfang der Szene gesehen hast: Ein Voll-Download wird an eine bereits teilweise geladene Datei angehängt. Ergebnis: Datei wirkt groß genug, ist aber logisch kaputt.

Erfolgssignal: 206 plus plausibles Content-Range

Wenn Resume wirklich funktioniert, siehst du typischerweise:

• Status 206 Partial Content statt 200 OK
• Content-Range mit Range-Unit bytes und dem erwarteten Start-Offset
• konsistente Validatoren (z. B. ETag), wenn du sie zur Versionstreue nutzt

Die Prüfungen sind nicht „nice to have“. RFC 9110 formuliert explizit, dass Empfänger eine 206-Antwort mit unbekannter Range-Unit nicht mit einer gespeicherten Repräsentation zusammensetzen dürfen. Praktische Folge: Ohne korrekt verstandenes Content-Range kein Append.^[Quelle]

If-Range und ETag: Der saubere Weg gegen Versionsmix

Das Kernproblem beim Fortsetzen ist nicht die Technik des Anhängens, sondern die Frage: Lädtst du noch dieselbe Ressource? HTTP liefert dafür Validatoren. ETag (Entity Tag) ist dabei der präziseste Hebel: ein Server-seitiger Bezeichner für eine konkrete Repräsentation. Last-Modified ist ein Datum, häufig brauchbar, aber weniger scharf (Zeitauflösung, Repackaging, unterschiedliche Zwischenstufen über CDNs).

Der Mechanismus für „Range nur dann, wenn es wirklich dieselbe Version ist“ heißt If-Range: Du sendest Range plus Bedingung. Passt der Validator, gibt es den Range; passt er nicht, soll der Server die komplette Ressource schicken. Für ETags gilt dabei: die Bedingung ist nur bei starkem ETag-Match erfüllt (strong comparison). Das ist nicht Interpretationssache, sondern so im Standard vorgesehen.^[Quelle]

Die Betriebsrealität bleibt: Wenn der Server Range nicht unterstützt, muss er If-Range ignorieren. Das klingt akademisch, ist aber eine direkte Anforderung an deinen Client: Du musst auch mit 200 OK rechnen und daraus eine harte Entscheidung ableiten (neu starten, nicht anhängen).^[Quelle]

Partial-File-Strategie: Das lokale Gegenstück zur HTTP-Semantik

Resume heißt: Du verwaltest lokalen Zustand. Und dieser Zustand muss auch nach Crash, Neustart, parallelem Start oder Benutzeraktion („nochmal klicken“) stabil bleiben. Eine saubere Partial-File-Strategie besteht aus drei Artefakten:

• Partial-Datei als einziger Schreibort während des Downloads (z. B. foo.zip.part)
• Metadaten getrennt gespeichert (z. B. foo.zip.part.meta.json): URL, Zeitpunkt, ETag, Last-Modified, erwartete Länge (falls bekannt), ggf. Content-Type, sowie die lokale Länge beim letzten sauberen Flush
• Atomarer Abschluss: erst nach vollständigem Download und Plausibilitätscheck wird auf den finalen Namen umbenannt/ersetzt

Warum Metadaten? Weil du sonst beim nächsten Start nur die Dateilänge kennst – aber nicht, ob sie zu genau dieser Server-Version gehört. Genau diese Information entscheidet, ob du fortsetzen darfst.

HttpClient Download mit Resume: Entscheidungslogik, die du testen kannst

System.Net.HttpClient liefert dir Requests, Responses und Streams. Die Robustheit kommt aus deiner Entscheidungsmatrix. Wenn du sie sauber formulierst, kannst du sie auch sauber testen (inklusive „Server ignoriert Range“, „Validator mismatch“, „416“).

Minimaler Ablauf in 6 Schritten

1. Lokalzustand ermitteln: Existiert .part? Länge als Offset lesen. Metadaten laden.
2. Resume-Fähigkeit entscheiden: Resume nur versuchen, wenn Offset > 0 und mindestens ein brauchbarer Validator in den Metadaten steht (ETag bevorzugt).
3. Request aufbauen: Range ab Offset setzen. Zusätzlich If-Range setzen (ETag, sonst Last-Modified).
4. Response klassifizieren:
   • 206: Content-Range parsen, Range-Unit bytes prüfen, Start-Offset muss exakt passen. Nur dann Append.
   • 200: nie Append. Partial-Stand verwerfen oder quarantänieren, neu herunterladen.
   • 416 Range Not Satisfiable: Offset passt nicht mehr (lokal oder serverseitig). Zustand resetten und neu starten.
   • sonst: Fehlerweg mit klarer Diagnose (Statuscode + Header loggen).
5. Stream schreiben: in Blöcken, regelmäßig flushen, Metadaten aktualisieren (z. B. „letzter Flush bei Länge X“).
6. Abschluss: Größen-/Plausibilitätscheck (wenn möglich). Dann atomar umbenennen/ersetzen.

RangeHeaderValue: kein Detail, sondern Fehlerprävention

.NET bietet für den Range-Header die typisierte Klasse RangeHeaderValue. Das ist nicht nur „schöner Code“: Es reduziert syntaktische Headerfehler und macht Logs interpretierbarer, weil du konsistente Werte erzeugst. Microsoft dokumentiert dabei auch die betrieblich relevante Kante: Server müssen Range-Requests nicht unterstützen; Accept-Ranges ist ein Hinweis, keine Zusage.^[Quelle]

Konstruiertes Beispiel: Wenn „200 OK“ dein Resume kaputtmacht

Typische Fallstricke und wie du sie im Log erkennst

Accept-Ranges: hilfreiches Signal, aber keine Garantie

Viele Teams nutzen Accept-Ranges als „Resume kann der Server“. MDN beschreibt den Header genau so als Support-Indikator („alles außer none“). Das ist praktisch für Diagnose und Telemetrie. Trotzdem: Entscheide nie nur danach. Ein Proxy, ein Auth-Gateway oder ein CDN kann das Verhalten ändern. Deine Logik muss deshalb immer am Statuscode (206 vs. 200) und am Content-Range hängen, nicht am Hoffnungsschimmer in Accept-Ranges.^[Quelle]

Weak ETags (W/…) und Transformationen

Weak ETags (W/"…") tauchen häufiger auf, als man möchte. Für If-Range ist aber ein starkes ETag-Match entscheidend. In der Praxis heißt das: Wenn du nur weak ETag bekommst, ist Resume weniger belastbar. Du kannst es weiterhin nutzen, aber du solltest konservativer sein (z. B. bei kleinsten Unstimmigkeiten neu starten) und bei besonders kritischen Dateien zusätzlich auf eine out-of-band-Integritätsprüfung setzen (Hash aus Manifest/API), falls verfügbar.

Unbekannte Gesamtlänge (chunked) und fehlende Plausibilität

Wenn keine Content-Length kommt (z. B. chunked Transfer), verlierst du den einfachen Abschlusscheck „lokale Länge == erwartete Länge“. Resume kann trotzdem funktionieren, aber du brauchst saubere Validatoren und gutes Logging. Ohne diese Stützen wird Fehlersuche zäh, weil du nicht einmal sagen kannst, ob dir Bytes fehlen oder zu viel da ist.

Parallelisierung: erst, wenn die Basis sitzt

Mehrere Ranges parallel laden ist möglich, aber es multipliziert Zustandsprobleme: Segmentverwaltung, Random-Write, Merge, Fehlerprotokoll, Retry pro Segment. Für viele prozessnahe Softwarelösungen ist das Overkill. Der stabile Gewinn kommt oft schon durch: seriellen Download + Resume + klare Entscheidungsmatrix. Parallelisierung lohnt sich erst, wenn du stabilen Range-Support nachgewiesen hast und konkrete Messwerte zeigen, dass du wirklich im Netzwerk- oder Serverlimit hängst.

Debugging, das in 5 Minuten Klarheit bringt

Resume-Bugs sind selten „nur ein falsches if“. Meist ist es eine Kombination aus Infrastruktur (Proxy/CDN), Server-Konfiguration, Timeouts und lokalem State. Darum lohnt sich strukturierte Protokollierung pro Versuch. Nicht als Textwüste, sondern als konsistente Felder:

• Request: URL (ohne Secrets), Methode, Range (Start/Ende), If-Range (ETag oder Datum).
• Response: Statuscode, Accept-Ranges, ETag, Last-Modified, Content-Length, Content-Range (roh und geparst).
• Lokaler Zustand: Part-Pfad, Part-Länge vor Request, Schreibmodus (Append/Overwrite), Länge nach dem Schreiben.
• Entscheidung: „Resume accepted“, „Resume rejected (200) – restart“, „416 – reset“, „Validator mismatch – restart“.

Mit genau diesen Daten kannst du Hypothesen testen: „Ignoriert der Server Range?“, „Wechselt der ETag zwischen Requests?“, „Ist der Offset falsch ermittelt?“, „Schreibt ein zweiter Prozess mit?“ – ohne dass du erst Wireshark auspacken musst.

Wann du bewusst kein Resume implementierst

Die sauberste Architekturentscheidung ist manchmal, Resume wegzulassen – nicht aus Bequemlichkeit, sondern weil es in deinem Szenario mehr Fehlerfläche als Nutzen bringt:

• URL ohne Versionsbindung: Wenn hinter derselben URL regelmäßig neue Inhalte liegen, ist Resume ohne starken Validator ein Integritätsrisiko.
• Keine brauchbaren Validatoren: Wenn weder ETag noch Last-Modified konsistent sind, ist „Fortsetzen“ eine Wette. Bei kritischen Importen ist das oft schlechter als ein kontrollierter Neustart.
• Download klein und häufig: Hier sind Retry-Strategien (Timeout, Backoff, ggf. Mirror-URL) wartbarer und im Betrieb leichter zu erklären.

Pragmatische Sicherheitsnetze, die sich auszahlen

Quarantäne statt Löschen

Wenn ein Resume-Versuch scheitert, lösche .part nicht reflexartig. Benenne um (z. B. .part.bad + Zeitstempel). Das macht Server-/Proxy-Probleme sichtbar, weil du später Response-Header und Dateistand gegenüberstellen kannst. Und es verhindert, dass ein seltenes Problem durch „Aufräumen“ direkt aus der Analyse verschwindet.

Locking gegen Doppelstarts

Wenn zwei Prozesse gleichzeitig dieselbe .part beschreiben, sind alle HTTP-Validatoren wertlos. Ein exklusiver Lock (Datei-Lock oder systemweiter Mutex) ist deshalb kein Luxus, sondern Grundschutz. Die Metadaten können zusätzlich eine Owner-Information tragen (Instanz-ID), damit du „verwaiste“ Downloads sauber erkennen und aufräumen kannst.

Spickzettel-Regeln, die du wirklich brauchst

• Append nur bei 206 – und nur mit geprüftem Content-Range (Unit bytes, Start-Offset passt).
• 200 heißt: neu starten (overwrite), nie an eine Partial-Datei anhängen.
• If-Range reduziert Versionsmix, ersetzt aber nicht die Pflicht, Status/Content-Range auszuwerten.
• 416 ist ein Reset-Signal: lokaler Offset passt nicht mehr, Zustand verwerfen/quarantänieren.

Schlusspunkt: Erst Integrität, dann Optimierung

Ein HttpClient Download mit Resume ist dann gut, wenn er langweilig ist: Er setzt Range nur, wenn der lokale Zustand belastbar ist, er hängt nur bei 206 plus geprüftem Content-Range an, und er verhindert Versionsmix über If-Range und Validatoren. Alles andere ist ein „sieht schnell aus“-Feature, das dir später Zeit frisst, weil Fehler selten sind und dann kaum nachstellbar.

Wenn du für Updater, Importstrecken oder Services eine robuste Download-Pipeline (Resume, Logging, Partial-File-Strategie, Betriebskanten) sauber aufsetzen willst, lässt sich das oft in einem kurzen Architektur-Check klären – inklusive der Frage, ob sich die Komplexität in deinem Umfeld überhaupt lohnt. Kontakt aufnehmen und Vorhaben mit Net-Base besprechen.

Projekt oder Modernisierungsvorhaben mit Net-Base besprechen.