Dateiexport zu Backblaze B2 in .NET mit Open-Source-Tools

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Exportieren Sie eine lokale Datei mit dem quelloffenen AWS SDK für .NET in einen bestehenden B2-Bucket. Dieses vollständige Konsolenbeispiel nutzt die S3-kompatible API von B2 und begrenzt jede Datei auf 64 MiB.

Einführung in den Cloud-Speicher Backblaze B2

B2 unterstützt eine native API und eine S3-kompatible API⁠. Hier verwenden wir S3-Vorgänge, Bucket-Namen sowie die Implementierung des AWS SDK für Signierung und Retries.

Ein Backblaze-B2-Konto einrichten

Erstellen Sie einen Bucket und einen dedizierten Anwendungsschlüssel mit Schreibberechtigung dafür. Notieren Sie den S3-Endpunkt und die Region des Buckets. Verwenden Sie die Schlüssel-ID des Anwendungsschlüssels als Zugriffsschlüssel und den Anwendungsschlüssel als geheimen Schlüssel; eine Konto-ID ersetzt die Schlüssel-ID nicht. Verwenden Sie für die S3-kompatible API einen standardmäßigen Anwendungsschlüssel, keinen Hauptschlüssel.

Erforderliche .NET-Bibliotheken installieren

Installieren Sie das .NET 10 SDK und erstellen Sie dann das Projekt mit diesen Paketen in festgelegten Versionen:

dotnet new console --framework net10.0 --name B2Export
cd B2Export
dotnet add package AWSSDK.Core --version 4.0.102.6
dotnet add package AWSSDK.S3 --version 4.0.103.3

Authentifizierung bei der Backblaze-B2-API in .NET

Stellen Sie diese Umgebungsvariablen über Ihre Shell oder Ihren Secret-Manager bereit, bevor Sie das Programm ausführen:

Die unten explizit angegebenen Zugangsdaten verhindern, dass das SDK ein AWS-Profil oder Instanzmetadaten durchsucht. Backblaze dokumentiert diese AWS-SDK-Konfiguration⁠.

Dateien mit C# zu Backblaze B2 hochladen

Ersetzen Sie Program.cs durch dieses vollständige Programm. Der Objektschlüssel wird unabhängig vom lokalen Dateinamen angegeben; übergeben Sie ihn ohne Escape-Sequenzen, damit das SDK Leerzeichen, Unicode und reservierte Zeichen codieren kann.

using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;

public static class B2Exporter
{
    public static async Task<int> Main(string[] args)
    {
        using var deadline = new CancellationTokenSource(TimeSpan.FromMinutes(5));
        Console.CancelKeyPress += (_, e) => { e.Cancel = true; deadline.Cancel(); };
        try
        {
            if (args.Length != 2) throw new ArgumentException("Pass a local file and an object key.");
            var endpoint = new Uri(Required("B2_ENDPOINT"));
            if (endpoint.Scheme != "https" || endpoint.UserInfo.Length != 0 ||
                endpoint.AbsolutePath != "/" || endpoint.Query.Length != 0 || endpoint.Fragment.Length != 0)
                throw new ArgumentException("Use the HTTPS regional endpoint without a bucket or path.");
            var config = new AmazonS3Config
            {
                ServiceURL = endpoint.AbsoluteUri,
                AuthenticationRegion = Required("B2_REGION"),
                ForcePathStyle = true,
                MaxErrorRetry = 2,
                RequestChecksumCalculation = RequestChecksumCalculation.WHEN_REQUIRED,
                ResponseChecksumValidation = ResponseChecksumValidation.WHEN_REQUIRED
            };
            using var client = new AmazonS3Client(
                Required("B2_KEY_ID"), Required("B2_APPLICATION_KEY"), config);
            await UploadAsync(client, Required("B2_BUCKET"), args[0], args[1], deadline.Token);
            Console.WriteLine("Uploaded.");
            return 0;
        }
        catch (OperationCanceledException) { Console.Error.WriteLine("Upload canceled or timed out."); }
        catch (AmazonS3Exception error) { Console.Error.WriteLine($"Storage returned HTTP {(int)error.StatusCode}."); }
        catch (Exception) { Console.Error.WriteLine("Upload failed. Check the file and storage configuration."); }
        return 1;
    }

    private static string Required(string name) =>
        Environment.GetEnvironmentVariable(name) is { Length: > 0 } value
            ? value : throw new ArgumentException($"Missing {name}.");

    public static async Task UploadAsync(IAmazonS3 client, string bucket, string path,
        string key, CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(key)) throw new ArgumentException("An object key is required.");
        await using var input = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read);
        if (input.Length > 64L * 1024 * 1024) throw new IOException("This example accepts at most 64 MiB.");
        await client.PutObjectAsync(new PutObjectRequest
        {
            BucketName = bucket,
            Key = key,
            InputStream = input,
            AutoCloseStream = false,
            ContentType = "application/octet-stream",
            UseChunkEncoding = false
        }, cancellationToken);
    }
}

Backblaze-Uploads in Ihre Anwendung integrieren

Erstellen Sie eine kleine Eingabedatei und führen Sie das Programm im Projektverzeichnis aus:

printf 'example export\n' > report.txt
dotnet run -- report.txt 'reports/report #1.txt'

UploadAsync akzeptiert eine Instanz von IAmazonS3 und ein Abbruchtoken, sodass eine Anwendung ihren Client wiederverwenden und einen Anfrageabbruch weitergeben kann. Der Aufrufer ist für den Client verantwortlich; die Methode schließt ihren Dateistream sowohl bei Erfolg als auch bei Fehlern. Lassen Sie die Quelldatei unverändert, bis der Upload abgeschlossen ist.

Fehlerbehebung und bewährte Verfahren

Bei Speicherfehlern, die einen erneuten Versuch erlauben, führt das SDK höchstens zwei Retries aus. Authentifizierungs- und Berechtigungsfehler erfordern Konfigurationsänderungen. Bei einer abgebrochenen oder fehlgeschlagenen Anfrage kann das Ergebnis auf dem Server ungewiss sein. Prüfen Sie daher das Objekt vor einem erneuten Versuch, wenn die Erstellung einer weiteren B2-Dateiversion relevant ist.

Dieses Beispiel sendet einen einzigen PUT mit einem Stream, auch bei leeren Dateien. Nutzen Sie für größere Exporte die Multipart-Funktionen des SDK und planen Sie die Bereinigung aufgegebener Multipart-Uploads ein. Für die Interoperabilität sind nur optionale SDK-Prüfsummen deaktiviert; HTTPS und die Signierung von Anfragen bleiben aktiviert.

Fazit

Das AWS SDK bietet einen vollständigen, unterstützten Ablauf für Signierung und Uploads ohne separaten Dependency-Injection-Adapter für B2. Wenn Sie Exporte mit Verarbeitung kombinieren möchten, sehen Sie sich den Dateiexport-Service von Transloadit an.