FILMY

Migracja z API Cloudmersive Barcode do IronBarcode

Curtis Chau
Curtis Chau
Updated: 19 maja 2026

To najprostsza migracja w historii BarCode'ów .NET. Usuń klienta HTTP. Dodaj pakiet NuGet. Usuń zarządzanie kluczami API. Reszta to po prostu wyszukiwanie i zamiana.

SDK .NET od Cloudmersive to wygenerowany klient API REST - cienka otoczka wokół wywołań HttpClient. Każdy fragment kodu specyficznego dla Cloudmersive w aplikacji to albo konfiguracja dla tego klienta, albo wywołania za pośrednictwem tego klienta, albo obsługa błędów w przypadku niepowodzenia żądań sieciowych. Żadna z tych infrastruktur nie jest potrzebna w przypadku IronBarcode, który przetwarza kody kreskowe lokalnie, bez zależności od sieci.

Szybki start: trzy kroki

Krok 1: Zamień pakiety

dotnet remove package Cloudmersive.APIClient.NET.Barcode
dotnet add package BarCode
SHELL

Krok 2: Zastąp przestrzenie nazw

// Remove these
using Cloudmersive.APIClient.NET.Barcode.Api;
using Cloudmersive.APIClient.NET.Barcode.Client;

// Add this
using IronBarCode;

Krok 3: Zastąp "Konfiguracja klucza API" przez "Klucz licencyjny"

// Remove this
Configuration.Default.ApiKey.Add("Apikey", "YOUR-CLOUDMERSIVE-API-KEY");

// Replace with this — set once at application startup
IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

W aplikacji ASP.NET Core klucz licencyjny umieszcza się w Program.cs przed builder.Build():

using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

var builder = WebApplication.CreateBuilder(args);
// ... rest of startup

Koszt: ile wydawałeś dotychczas a ile wydasz

Przed migracją warto obliczyć, ile faktycznie kosztuje integracja z Cloudmersive. Rachunek jest prosty:

Twoja dzienna liczba słówMiesięczne zleceniaPoziom CloudmersiveIronBarcode (jednorazowe zlecenie)
100/dzień~3 000Podstawowy $19.99/miesiąc$999
1000/dzień~30 000Biznesowy Premier $99.99/miesiąc$999
5 000/dzień~150 000Średni Biznes $499.99/miesiąc$999
10 000/dzień~300 000Enterprise (niestandardowy)$999
25 000/dzień~750 000Enterprise (niestandardowy)1499 USD (Plus 3 programistów)

Jeśli płacisz więcej niż ~$63/miesiąc dla Cloudmersive, Lite licencja IronBarcode opłaca się w ciągu pierwszego roku. Po osiągnięciu progu rentowności IronBarcode jest licencją wieczystą bez odnowień i opłat za żądanie.

Przykłady migracji kodu

Generowanie kodów QR

Najpopularniejsze mapy wywołań generacji Cloudmersive odpowiadają bezpośrednio IronBarcode:

Przed (Cloudmersive):

using Cloudmersive.APIClient.NET.Barcode.Api;
using Cloudmersive.APIClient.NET.Barcode.Client;

Configuration.Default.ApiKey.Add("Apikey", "YOUR-CLOUDMERSIVE-API-KEY");

var apiInstance = new GenerateBarcodeApi();

byte[] result = apiInstance.GenerateBarcodeQRCode("https://example.com");
File.WriteAllBytes("qr.png", result);

Po (IronBarcode):

using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

byte[] result = QRCodeWriter.CreateQrCode("https://example.com", 500)
    .ToPngBinaryData();
File.WriteAllBytes("qr.png", result);

// Or save directly
QRCodeWriter.CreateQrCode("https://example.com", 500)
    .SaveAsPng("qr.png");

Generowanie kodu 128

Przed (Cloudmersive):

using Cloudmersive.APIClient.NET.Barcode.Api;
using Cloudmersive.APIClient.NET.Barcode.Client;

Configuration.Default.ApiKey.Add("Apikey", "YOUR-CLOUDMERSIVE-API-KEY");
var apiInstance = new GenerateBarcodeApi();

byte[] result = apiInstance.GenerateBarcodeCode128("SHIP-2024031500428");
File.WriteAllBytes("barcode.png", result);

Po (IronBarcode):

using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

BarcodeWriter.CreateBarcode("SHIP-2024031500428", BarcodeEncoding.Code128)
    .SaveAsPng("barcode.png");

// Or get bytes directly
byte[] result = BarcodeWriter.CreateBarcode("SHIP-2024031500428", BarcodeEncoding.Code128)
    .ToPngBinaryData();

Odczytywanie BarCode

Przed (Cloudmersive):

using Cloudmersive.APIClient.NET.Barcode.Api;
using Cloudmersive.APIClient.NET.Barcode.Client;

Configuration.Default.ApiKey.Add("Apikey", "YOUR-CLOUDMERSIVE-API-KEY");
var scanApi = new BarcodeScanApi();

using (var stream = File.OpenRead("barcode.png"))
{
    var result = scanApi.BarcodeScanImage(stream);
    if (result.Successful == true)
    {
        Console.WriteLine($"Value: {result.RawText}");
        Console.WriteLine($"Type: {result.BarcodeType}");
    }
}

Po (IronBarcode):

using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

var results = BarcodeReader.Read("barcode.png");
var result = results.First();
Console.WriteLine($"Value: {result.Value}");
Console.WriteLine($"Type: {result.Format}");

Asynchroniczne odczytywanie BarCodes

Jeśli Twoja integracja z Cloudmersive wykorzystuje asynchroniczny interfejs API:

Przed (Cloudmersive):

using Cloudmersive.APIClient.NET.Barcode.Api;
using Cloudmersive.APIClient.NET.Barcode.Client;

Configuration.Default.ApiKey.Add("Apikey", "YOUR-CLOUDMERSIVE-API-KEY");
var scanApi = new BarcodeScanApi();

using (var stream = File.OpenRead("barcode.png"))
{
    var result = await scanApi.BarcodeScanImageAsync(stream);
    return result.Successful == true ? result.RawText : null;
}

Po (IronBarcode):

using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

// IronBarcode is synchronous; wrap in Task.Run to free the calling thread for CPU-bound work
var results = await Task.Run(() => BarcodeReader.Read("barcode.png"));
return results.FirstOrDefault()?.Value;

Odczytywanie BarCodes z plików PDF

Cloudmersive nie obsługuje natywnie plików PDF. Jeśli istniejący kod wyodrębnia obrazy z plików PDF przed skanowaniem, zastąp cały ten proces pojedynczym wywołaniem IronBarcode:

Przed (Cloudmersive - wymaga oddzielnego wyodrębnienia pliku PDF):

// Requires a separate PDF library to extract pages as images,
// then one Cloudmersive API call per extracted page image.
var scanApi = new BarcodeScanApi();
foreach (var pageImagePath in ExtractPdfPages("document.pdf"))
{
    using var stream = File.OpenRead(pageImagePath);
    var result = await scanApi.BarcodeScanImageAsync(stream);
    if (result.Successful == true)
    {
        Console.WriteLine($"Found: {result.RawText}");
    }
}

Po (IronBarcode):

using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

// One call — all pages, all barcodes, no image extraction step
var results = BarcodeReader.Read("document.pdf");
foreach (var result in results)
{
    Console.WriteLine($"Page {result.PageNumber}: {result.Value}");
}

Wykrywanie wielu BarCodes

Jeśli masz kod, który skanuje dokumenty z wieloma BARCODE'ami:

Przed (Cloudmersive - wymagane wielokrotne wywołania):

// Cloudmersive returns one barcode per scan — multiple calls for multiple barcodes
var scanApi = new BarcodeScanApi();
var barcodeValues = new List<string>();

foreach (var croppedRegion in CropBarcodeRegions("invoice.png"))
{
    using var stream = new MemoryStream(croppedRegion);
    var result = await scanApi.BarcodeScanImageAsync(stream);
    if (result.Successful == true)
        barcodeValues.Add(result.RawText);
}

Po (IronBarcode):

using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectMultipleBarcodes = true,
};

// One call — returns all barcodes in the image
var results = BarcodeReader.Read("invoice.png", options);
var barcodeValues = results.Select(r => r.Value).ToList();

Usuwanie infrastruktury, która nie jest już potrzebna

Jest to etap migracji, w którym usuwa się więcej kodu niż się pisze.

Usuń obsługę wyjątków HTTP

Operacje Cloudmersive mogą zakończyć się niepowodzeniem z powodu błędów sieciowych, odpowiedzi HTTP 4xx/5xx oraz wyjątków związanych z przekroczeniem limitu czasu. Zazwyczaj powoduje to powstanie infrastruktury try/catch, której IronBarcode nie potrzebuje:

// Remove all of this
try
{
    var result = await scanApi.BarcodeScanImageAsync(stream);
    // ...
}
catch (ApiException ex) when (ex.ErrorCode == 429)
{
    // Rate limited — wait and retry
    await Task.Delay(TimeSpan.FromSeconds(2));
    // retry logic...
}
catch (ApiException ex) when (ex.ErrorCode == 503)
{
    // Service unavailable — Cloudmersive is down
    _logger.LogError("Cloudmersive unavailable: {Message}", ex.Message);
    throw;
}
catch (HttpRequestException ex)
{
    // Network error
    _logger.LogError("Network failure: {Message}", ex.Message);
    throw;
}
catch (TaskCanceledException)
{
    // Timeout
    _logger.LogError("Cloudmersive request timed out");
    throw;
}

IronBarcode nie generuje wyjątków sieciowych. Rzuca BarcodeException, jeśli kod kreskowy nie może być zdekodowany z danych wejściowych, co jest problemem z zawartością, a nie z infrastrukturą. Uproszczona obsługa błędów:

using IronBarCode;

var results = BarcodeReader.Read("barcode.png");
if (!results.Any())
{
    _logger.LogWarning("No barcode detected in image");
}

Usuń logikę ponownej próby

Jeśli Twoja integracja z Cloudmersive zawiera zasady ponownych prób - Polly, niestandardowe pętle ponownych prób lub wykładniczy backoff - usuń je całkowicie:

// Remove retry infrastructure
// var retryPolicy = Policy
//     .Handle<ApiException>()
//     .WaitAndRetryAsync(3, retryAttempt =>
//         TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));

// IronBarcode — no retry needed
var results = BarcodeReader.Read("barcode.png");

Usuń śledzenie limitów szybkości

Jeśli Twój kod śledzi liczbę wywołań API, aby nie przekroczyć miesięcznego limitu Cloudmersive:

// Remove quota tracking
// private static int _monthlyCallCount = 0;
// private const int MonthlyLimit = 30000;
//
// if (Interlocked.Increment(ref _monthlyCallCount) > MonthlyLimit)
//     throw new InvalidOperationException("Monthly Cloudmersive quota exceeded");

// IronBarcode — no quota
var results = BarcodeReader.Read("barcode.png");

Usuń konfigurację limitu czasu sieciowego

Klienci Cloudmersive często uwzględniają konfigurację limitu czasu. Usuń to:

// Remove timeout configuration
// Configuration.Default.Timeout = 30000; // 30 second timeout
// Configuration.Default.ConnectionTimeout = 5000;

// IronBarcode has no network timeout — no network

Usuń rotację kluczy API

Jeśli Twoja aplikacja zmienia klucze API zgodnie z harmonogramem lub przechowuje je w systemie zarządzania sekretami:

// Simplify this pattern
// private string GetCloudmersiveApiKey() =>
//     _secretManager.GetSecret("cloudmersive-api-key-current");
//
// Configuration.Default.ApiKey["Apikey"] = GetCloudmersiveApiKey();

// IronBarcode — set once at startup
IronBarCode.License.LicenseKey = _configuration["IronBarcode:LicenseKey"];
// or literal: "YOUR-LICENSE-KEY"

Typowe problemy związane z migracją

Cloudmersive zwrócił byte[] dla generacji

Metody generowania w Cloudmersive zwracają bezpośrednio byte[]. IronBarcode zwraca obiekt GeneratedBarcode, który daje więcej opcji:

// Cloudmersive returned byte[] directly
byte[] cloudmersiveResult = apiInstance.GenerateBarcodeQRCode("data");

// IronBarcode — call ToPngBinaryData() for the equivalent byte[]
byte[] ironBarcodeResult = BarcodeWriter.CreateBarcode("data", BarcodeEncoding.QRCode)
    .ToPngBinaryData();

// Or save directly (often simpler)
BarcodeWriter.CreateBarcode("data", BarcodeEncoding.QRCode)
    .SaveAsPng("output.png");

// Or get other formats
byte[] jpegBytes = BarcodeWriter.CreateBarcode("data", BarcodeEncoding.QRCode)
    .ToJpegBinaryData();

Cloudmersive Reading zwróciło model odpowiedzi JSON

Wynik skanowania Cloudmersive to model odpowiedzi z właściwościami takimi jak Successful, RawText i BarcodeType. IronBarcode zwraca obiekty wyników typu:

// Cloudmersive result model
if (cloudmersiveResult.Successful == true)
{
    string value = cloudmersiveResult.RawText;
    string type = cloudmersiveResult.BarcodeType;
}

// IronBarcode result — use .Value and .Format directly
var results = BarcodeReader.Read("barcode.png");
if (results.Any())
{
    string value = results.First().Value;
    string format = results.First().Format.ToString();
}

Wiele typów instancji API Cloudmersive

Cloudmersive rozdziela generowanie i skanowanie na instancje GenerateBarcodeApi i BarcodeScanApi. IronBarcode wykorzystuje klasy statyczne - nie są potrzebne żadne instancje:

// Cloudmersive — two separate API instances
var generateApi = new GenerateBarcodeApi();
var scanApi = new BarcodeScanApi();

// IronBarcode — static, no instances
// BarcodeWriter for generation
// BarcodeReader for reading
// QRCodeWriter for QR codes specifically

Lista kontrolna migracji

Przeprowadź te wyszukiwania w swoim kodzie przed i po migracji, aby sprawdzić, czy wychwyciłeś wszystkie odniesienia do Cloudmersive:

# Find all Cloudmersive references
grep -r "Cloudmersive" --include="*.cs" .
grep -r "GenerateBarcodeApi" --include="*.cs" .
grep -r "BarcodeScanApi" --include="*.cs" .
grep -r "Configuration.Default.ApiKey" --include="*.cs" .
grep -r '"Apikey"' --include="*.cs" .
grep -r "GenerateBarcodeQRCode" --include="*.cs" .
grep -r "GenerateBarcodeCode128" --include="*.cs" .
grep -r "BarcodeScanImage" --include="*.cs" .
grep -r "cloudmersive" --include="*.csproj" .
grep -r "cloudmersive" --include="*.json" .
SHELL

Po migracji wszystkie wyszukiwania powinny zwracać zero wyników. Następnie sprawdź, czy IronBarcode jest poprawnie przywołany:

grep -r "IronBarCode" --include="*.cs" .
grep -r "BarcodeReader" --include="*.cs" .
grep -r "BarcodeWriter" --include="*.cs" .
SHELL

Lista kontrolna konfiguracji

  • Usuń Cloudmersive.APIClient.NET.Barcode ze wszystkich plików .csproj
  • Usuń klucz API Cloudmersive z appsettings.json, zmiennych środowiskowych i magazynów sekretów
  • Dodaj pakiet NuGet IronBarcode
  • Dodaj inicjalizację IronBarCode.License.LicenseKey przy starcie aplikacji
  • Usuń zasady ponownych prób i mechanizmy zabezpieczające dla wywołań Cloudmersive
  • Usuń kod śledzenia limitów częstotliwości
  • Usuń konfigurację limitu czasu sieciowego

Lista kontrolna do testowania

Po zakończeniu migracji:

  • Sprawdź, czy generowanie kodów QR daje poprawny wynik, który można zeskanować
  • Weryfikacja generowania kodów Code128 i innych kodów kreskowych liniowych
  • Sprawdź odczyt BARCODE-ów z popularnych formatów obrazów (PNG, JPEG, BMP)
  • Sprawdź odczyt plików PDF, jeśli przetwarzasz dokumenty w formacie PDF
  • W razie potrzeby przetestuj wykrywanie wielu BarCodes
  • Upewnij się, że w ruchu sieciowym nie pojawiają się żadne wywołania API Cloudmersive
  • Sprawdź, czy aplikacja działa poprawnie bez połączenia z Internetem

Co zyskujesz po migracji

Oprócz oszczędności kosztów migracja eliminuje całą gamę problemów operacyjnych:

Koniec z przetwarzaniem kodów kreskowych zależnym od sieci. Twój proces przetwarzania dokumentów działa niezależnie od dostępności Cloudmersive, jakości połączenia internetowego czy skoków opóźnień sieciowych.

Koniec z zarządzaniem limitami. Skoki w ilości dokumentów pod koniec miesiąca nie powodują niespodziewanych przekroczeń limitów ani błędów przetwarzania.

Żadne dane nie opuszczają już Twojej sieci. Obrazy BARCODE zawierające poufne informacje o klientach, dane finansowe lub informacje dotyczące zdrowia pozostają w Twojej infrastrukturze.

Prostszy kod. Zniknęła infrastruktura ponownych prób, obsługa limitów czasu i zarządzanie wyjątkami HTTP, które są wymagane w produkcyjnych integracjach Cloudmersive. Zastępuje to bezpośrednie wywołanie metody.

Migracja ma charakter mechaniczny. Korzyści mają charakter strukturalny - eliminują zależność od zewnętrznej usługi sieciowej z procesu, który jej nie wymaga.

Curtis Chau
Curtis Chau
Autor tekstów technicznych

Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.

Czytaj więcej

Powiązane artykuły