Wprowadzenie

Przedsiębiorstwa przechowujące umowy, sprawozdania finansowe lub dokumenty regulacyjne muszą utrzymywać te pliki PDF w formacie archiwalnym – PDF/A. Jeśli choć jeden plik nie spełnia wymaganego poziomu zgodności, audytorzy mogą oznaczyć całą partię, a kosztowne ponowne przetwarzanie może zostać uruchomione miesiące później. Poleganie na ręcznych kontrolach szybko staje się niepraktyczne, gdy codziennie napływa setki plików.

GroupDocs.Metadata dla .NET usuwa zgadywanie. Dzięki wyraźnemu IsPdfA oraz dokładnej enumeracji PdfFormat, biblioteka w jednej linii informuje, czy dokument spełnia którykolwiek poziom PDF/A i, jeśli tak, jaki konkretny wariant (np. PDF/A‑1b, PDF/A‑2u) jest spełniony. W tym samouczku zobaczysz, jak podłączyć tę logikę do aplikacji konsolowej, udostępnić ją przez API webowe i skalować do przetwarzania wsadowego.

Po zakończeniu przewodnika będziesz w stanie:

  • Załadować PDF przy użyciu klasy Metadata.
  • Określić zgodność PDF/A przy pomocy właściwości logicznej.
  • Wyodrębnić dokładną wersję PDF/A dla zgodnych plików.
  • Zintegrować sprawdzenie z większymi przepływami pracy (zadania wsadowe, API, funkcje serverless).

Dlaczego dokładne wykrywanie PDF/A jest kluczowe

Niezawodne, zautomatyzowane sprawdzenie pomaga:

  • Być gotowym na audyt: Udowodnij regulatorom, że każdy przechowywany PDF spełnia standard ISO 19005.
  • Zachować wierność wizualną: PDF/A gwarantuje, że czcionki, kolory i układ przetrwają w przyszłych przeglądarkach.
  • Zautomatyzować potoki ingestii: Odrzuć niezgodne pliki, zanim trafią do systemu zarządzania dokumentami.
  • Uniknąć kosztownych poprawek: Wczesne wykrycie zapobiega drogiemu ponownemu walidowaniu partii w późniejszym etapie cyklu życia.

Wymagania wstępne

  • .NET 6.0 lub nowszy.
  • GroupDocs.Metadata pakiet NuGet (najnowsza wersja).
  • Jeden lub więcej plików PDF, które chcesz ocenić.
  • (Opcjonalnie) Tymczasowa licencja ewaluacyjna – możesz ją uzyskać w portalu GroupDocs.

Instalacja

Utwórz nowy projekt konsolowy i dodaj pakiet:

dotnet new console -n DetectPdfA
cd DetectPdfA

dotnet add package GroupDocs.Metadata

Krok 1 – Inicjalizacja silnika Metadata

Najpierw otwieramy PDF przy użyciu klasy Metadata. Konstruktor automatycznie rozpoznaje format pliku, więc nie są potrzebne dodatkowe parametry.

using GroupDocs.Metadata;

string pdfPath = "sample.pdf";

// Otwórz dokument – blok using zapewnia zwolnienie uchwytu pliku.
using (Metadata metadata = new Metadata(pdfPath))
{
    // Kolejne kroki będą tutaj.
}

Kluczowy punkt: Instrukcja using zapewnia szybkie zwolnienie zasobów natywnych, zapobiegając wyciekom uchwytów plików w usługach działających długo.

Krok 2 – Pobranie pakietu głównego specyficznego dla PDF

GroupDocs.Metadata udostępnia silnie typowany obiekt główny dla każdego formatu. Dla PDF‑ów żądamy PdfRootPackage, który zawiera potrzebne informacje o FileType.

using GroupDocs.Metadata.Formats.Pdf;

// Wewnątrz bloku using z Kroku 1
var root = metadata.GetRootPackage<PdfRootPackage>();

root.FileType posiada dwie interesujące właściwości:

  • IsPdfA – true, jeśli dokument spełnia którykolwiek poziom PDF/A.
  • PdfFormat – wyliczenie takie jak PdfA1b, PdfA2u itd., wskazujące dokładną wersję.

Krok 3 – Wykonanie sprawdzenia zgodności

Teraz odczytujemy flagę i, jeśli ma to zastosowanie, wypisujemy konkretny wariant PDF/A.

if (root.FileType.IsPdfA)
{
    // Dokument jest zgodny – raportujemy dokładną wersję.
    Console.WriteLine($"✅ PDF/A compliant – version: {root.FileType.PdfFormat}");
}
else
{
    // Dokument nie spełnia wymagań PDF/A.
    Console.WriteLine("❌ The document is NOT PDF/A compliant.");
}

Co widzisz:

  • Pojedyncza wartość logiczna (IsPdfA) daje natychmiastową odpowiedź tak/nie.
  • Gdy true, PdfFormat dostarcza precyzyjny poziom zgodności, który możesz zapisać w logach, bazach danych lub raportach audytowych.

Kompletny działający przykład

Połączenie trzech kroków w jedną, gotową do skopiowania i wklejenia aplikację:

using System;
using GroupDocs.Metadata;
using GroupDocs.Metadata.Formats.Pdf;

class Program
{
    static void Main(string[] args)
    {
        string pdfPath = "sample.pdf";

        using (Metadata metadata = new Metadata(pdfPath))
        {
            var root = metadata.GetRootPackage<PdfRootPackage>();

            if (root.FileType.IsPdfA)
            {
                Console.WriteLine($"✅ PDF/A compliant – version: {root.FileType.PdfFormat}");
            }
            else
            {
                Console.WriteLine("❌ The document is NOT PDF/A compliant.");
            }
        }
    }
}

Uruchom program poleceniem dotnet run. Przykładowy wynik dla zgodnego pliku może wyglądać tak:

✅ PDF/A compliant – version: PdfA2u

A dla niezgodnego:

❌ The document is NOT PDF/A compliant.

Zastosowania w rzeczywistym świecie

1. Zautomatyzowane potoki archiwizacji – Monitoruj folder docelowy, waliduj każdy PDF przy pomocy powyższego fragmentu i przenoś tylko zgodne pliki do warstwy długoterminowego przechowywania.

2. Walidacja uploadów w portalu webowym – Owiń tę samą logikę w kontrolerze ASP.NET Core (zobacz opcjonalny fragment kodu poniżej), aby odrzucać nie‑PDF/A przed ich zapisaniem.

3. Serverless – sprawdzanie zgodności – Wdroż metodę jako Azure Function wywoływaną przy tworzeniu BLOB‑a, zwracającą ładunek JSON ze statusem zgodności.

// Minimalny fragment payloadu Azure Function (excerpt)
var result = new
{
    file = file.FileName,
    isPdfA = root.FileType.IsPdfA,
    format = root.FileType.IsPdfA ? root.FileType.PdfFormat.ToString() : null
};

Najlepsze praktyki i wskazówki

  • Waliduj ścieżkę najpierw – użyj Path.GetFullPath i sprawdź istnienie przed utworzeniem Metadata, aby uniknąć FileNotFoundException.
  • Utrzymuj bibliotekę w najnowszej wersji – nowsze wydania poprawiają wykrywanie formatów i naprawiają błędy brzegowe.
  • Zwalniaj zasoby od razu – wzorzec using pokazany w całym przewodniku zapewnia zwolnienie zasobów natywnych.
  • Obsługuj wyjątki – otocz konstruktor w try/catch i loguj MetadataException w przypadku uszkodzonych PDF‑ów.
  • Równoległość przy dużych partiach – twórz osobną instancję Metadata dla każdego pliku wewnątrz Parallel.ForEach; API jest bezpieczne wątkowo, o ile instancje nie są współdzielone.

Rozwiązywanie typowych problemów

Problem: root.FileType.PdfFormat zwraca null, mimo że IsPdfA jest true.

  • Rozwiązanie: Upewnij się, że używasz GroupDocs.Metadata v23.6+ gdzie enum jest w pełni wypełniony. Aktualizacja pakietu NuGet zazwyczaj rozwiązuje problem.

Problem: Aplikacja wywala FileFormatException przy uszkodzonym PDF‑ie.

  • Rozwiązanie: Otocz wywołanie new Metadata(pdfPath) w try/catch, zaloguj nazwę pliku i pomiń go w scenariuszach wsadowych.

Problem: Wysokie zużycie pamięci przy przetwarzaniu PDF‑ów wielogigabajtowych.

  • Rozwiązanie: Włącz tryb strumieniowy, tworząc Metadata z FileStream i flagą enableStreaming ustawioną na true (np. new Metadata(stream, true)).

Dodatkowe zasoby