Warum Ihre Shapefile‑Konvertierung fehlschlägt und wie Sie sie in C# beheben.

Sie führen eine Shapefiles Konvertierung durch, die bereits hundertmal funktioniert hat, und diesmal bricht sie mit einer TransformationException ab. Es gibt keine Teilausgabe und keinen klaren Hinweis darauf, welcher Datensatz das Problem verursacht hat. Oft ist der Schuldige ein einzelner ungültiger Koordinatenwert, der zwischen Tausenden gültiger Features verborgen ist. Dieser Artikel erklärt, warum die Shapefile‑Konvertierung mit diesem Fehler fehlschlägt und wie man ihn in C# mit OperationErrorCollector, eingeführt in Aspose.GIS for .NET 26.6, behebt. Sie erfahren, wie Sie die Konvertierung bis zum Ende laufen lassen, jedes gültige Feature behalten und einen genauen Bericht über die Datensätze erhalten, die Aufmerksamkeit benötigen.

Wenn Sie nur den grundlegenden Konvertierungscode benötigen, siehe Convert Shapefile to KML in C#. Dieser Leitfaden baut darauf auf und konzentriert sich auf die Behandlung von Fehlern.

Warum Shapefile-Konvertierung TransformationException wirft

Die meisten Zielformate erwarten Koordinaten in einem bestimmten Koordinatensystem. KML verwendet beispielsweise immer WGS 84 Längen- und Breitengrad. Während der Konvertierung transformiert Aspose.GIS jede Koordinate vom Quellkoordinatensystem in das Zielkoordinatensystem. Wenn eine Koordinate nicht transformiert werden kann, wirft die Bibliothek eine TransformationException und die Konvertierung wird abgebrochen.

Die häufigsten Ursachen sind:

• Platzhalter-“keine Daten”-Werte. Einige Werkzeuge schreiben einen Sentinelwert, anstatt eine Geometrie leer zu lassen. Die Beispieldatei in diesem Artikel enthält einen Punkt bei (-1.7976931348623157E+308, -1.7976931348623157E+308), dem Minimalwert eines double, den kein Koordinatensystem transformieren kann.
• Koordinaten außerhalb des gültigen Bereichs. Werte, die außerhalb des gültigen Bereichs des Quellkoordinatensystems liegen, häufig verursacht durch Eingabefehler oder falsche Einheitumrechnungen.
• Eine .prj-Datei, die nicht zu den Daten passt. Wenn projizierte Koordinaten in Metern als geografische Koordinaten in Grad deklariert werden, landen viele Werte weit außerhalb des gültigen Bereichs.
• Beschädigte Geometrierekorde. Legacy-Exporte und beschädigte Dateien können ungültige numerische Werte in einzelnen Datensätzen enthalten.

In jedem Fall ist das Problem in der Regel auf eine Handvoll Datensätze beschränkt, doch das Standardverhalten verwirft die gesamte Konvertierung.

Warum diese Funktion wichtig ist

Das Anhalten beim ersten Fehler ist sicher, aber es ist in realen Pipelines kostspielig. Ein fehlerhafter Datensatz zwingt Sie dazu, die Datei von Hand zu bereinigen, bevor Daten konvertiert werden können, und die Ausnahme allein sagt nicht, wie viele weitere Datensätze betroffen sind. Mit aktivierter Fehlersammlung können Sie:

• Konvertieren Sie alle gültigen Features, anstatt die gesamte Datei zu einem fehlerhaften Datensatz zu verlieren.
• Protokollieren Sie den Index und die Koordinaten jedes übersprungenen Features, damit die Quelldaten repariert werden können.
• Führen Sie unbeaufsichtigte Batch‑Konvertierungen und ETL‑Jobs aus, ohne bei fehlerhaften Eingaben abzustürzen.
• Akzeptieren Sie von Benutzern hochgeladene Shapefiles in Webdiensten und melden Sie Datenprobleme zurück an den Benutzer.

So beheben Sie Shapefile-Konvertierungsfehler in C# mit Aspose.GIS

Aspose.GIS for .NET ist eine verwaltete Bibliothek zum Lesen, Schreiben und Konvertieren von Geodatenformaten wie Shapefile, KML, GeoJSON, GML und File Geodatabase, ohne dass weitere GIS-Software installiert sein muss. Die Fehlererfassung erfordert Version 26.6 oder höher. Installieren Sie das Paket über NuGet:

dotnet add package Aspose.GIS

Oder verwenden Sie die Package Manager Console:

Install-Package Aspose.GIS

Die folgenden Typen werden in diesem Tutorial verwendet:

• VectorLayer (Aspose.Gis): öffnet, erstellt und konvertiert Vektorebenen. VectorLayer.Convert führt die Konvertierung durch.
• ConversionOptions (Aspose.Gis): enthält Konvertierungseinstellungen, einschließlich DestinationDriverOptions und DestinationSpatialReferenceSystem.
• KmlOptions (Aspose.Gis.Formats.Kml): KML‑Treiberoptionen. Sie erbt die ErrorCollector‑Eigenschaft von DriverOptions.
• OperationErrorCollector (Aspose.Gis.Operations): speichert wiederherstellbare Fehler. Sie stellt Errors, Count, HasErrors, Add und Clear bereit.
• OperationError und TransformationError (Aspose.Gis.Operations): jeder Fehler hat eine Message und eine Exception. TransformationError fügt FeatureIndex, X, Y und Z hinzu.
• TransformationException (Aspose.Gis.SpatialReferencing): wird ausgelöst, wenn ein Koordinatensatz nicht transformiert werden kann und kein Sammler angehängt ist.

Wie man TransformationException bei der Shapefile-Konvertierung behebt

Die Lösung besteht aus zwei Teilen. Erstens fügen Sie einen OperationErrorCollector hinzu, damit die Konvertierung ungültige Features überspringt, anstatt zu fehlschlagen. Zweitens verwenden Sie den gesammelten Bericht, um diese Datensätze an der Quelle zu reparieren oder zu entfernen. Die nachstehenden Schritte verwenden eine Shapefile‑zu‑KML‑Konvertierung als Beispiel.

1. Umgebung vorbereiten

1. Erstellen Sie ein .NET‑Konsolenprojekt und fügen Sie das NuGet‑Paket Aspose.GIS 26.6+ hinzu.
2. Kopieren Sie die Shapefile und ihre Begleitdateien (.shp, .shx, .dbf und .prj) in einen Ordner. Dieses Beispiel verwendet data/light-traffics.shp.
3. Fügen Sie die erforderlichen Namespaces hinzu:

using System;
using System.IO;
using Aspose.Gis;
using Aspose.Gis.Formats.Kml;
using Aspose.Gis.Operations;
using Aspose.Gis.SpatialReferencing;

2. Erstellen eines OperationErrorCollector

Der Sammler protokolliert jeden wiederherstellbaren Fehler, der während der Konvertierung auftritt. Erstellen Sie für jede Konvertierung eine neue Instanz, damit Fehler aus verschiedenen Dateien nicht vermischt werden.

// Records recoverable errors instead of throwing them.
var errors = new OperationErrorCollector();

3. Den Collector über ConversionOptions anhängen

Ordnen Sie den Sammler KmlOptions.ErrorCollector zu und übergeben Sie dann die KML‑Optionen als DestinationDriverOptions. Das Festlegen von DestinationSpatialReferenceSystem auf WGS 84 ist für KML optional, aber es macht das Zielkoordinatensystem in Ihrem Code explizit.

var options = new ConversionOptions
{
    // KML always uses WGS 84; stating it makes the reprojection explicit.
    DestinationSpatialReferenceSystem = SpatialReferenceSystem.Wgs84,
    DestinationDriverOptions = new KmlOptions
    {
        ErrorCollector = errors // Skip and record features that fail transformation.
    }
};

4. Konvertierung ausführen

Rufen Sie VectorLayer.Convert mit dem Quellpfad, dem Shapefile‑Treiber, dem Zielpfad, dem KML‑Treiber und den gerade konfigurierten Optionen auf.

string sourcePath = Path.Combine("data", "light-traffics.shp");
string destinationPath = Path.Combine("output", "light-traffics.kml");
Directory.CreateDirectory(Path.GetDirectoryName(destinationPath));

VectorLayer.Convert(sourcePath, Drivers.Shapefile, destinationPath, Drivers.Kml, options);

Wenn ein Feature nicht transformiert werden kann, fügt der KML‑Treiber einen Fehler zum Collector hinzu, überspringt dieses Feature und fährt mit dem nächsten fort. Es wird keine TransformationException ausgelöst.

5. Übersprungene Funktionen melden und die Ausgabe überprüfen

Eine Konvertierung, die normal zurückkehrt, kann dennoch übersprungene Features haben, daher sollten Sie immer anschließend den Collector überprüfen. Casten Sie jeden Fehler zu TransformationError, um den Feature‑Index und die fehlerhafte Koordinate zu erhalten, und öffnen Sie dann die Ausgabedatei, um zu bestätigen, wie viele Features geschrieben wurden.

if (errors.HasErrors)
{
    Console.WriteLine($"Skipped {errors.Count} feature(s):");

foreach (var error in errors.Errors)
    {
        if (error is TransformationError transformationError)
        {
            Console.WriteLine(
                $"  Feature #{transformationError.FeatureIndex} at " +
                $"({transformationError.X}, {transformationError.Y}, {transformationError.Z}): {error.Message}");
        }
        else
        {
            Console.WriteLine($"  {error.Message}");
        }
    }
}

using (var layer = VectorLayer.Open(destinationPath, Drivers.Kml))
{
    Console.WriteLine($"Features written to KML: {layer.Count}");
}

Für die Beispieldatei protokolliert der Sammler einen Fehler für den Platzhalterpunkt, und die übrigen Features (mindestens 444) werden in die KML‑Datei geschrieben.

Der Feature‑Index und die Koordinaten in diesem Bericht vervollständigen die Korrektur. Öffnen Sie die Quell‑Shapefile in Ihrem Datenbereinigungs‑Workflow, suchen Sie die gemeldeten Datensätze und korrigieren oder entfernen Sie sie. Wenn viele Datensätze mit plausibel aussehenden Werten fehlschlagen, prüfen Sie zuerst die .prj‑Datei, da ein nicht übereinstimmendes Koordinatensystem die wahrscheinliche Ursache ist.

6. Vollständiger Beispielcode

Die vollständige Konsolenanwendung unten führt die Konvertierung zweimal aus. Der erste Durchlauf verwendet die Standardeinstellungen und reproduziert die TransformationException. Der zweite Durchlauf fügt einen OperationErrorCollector hinzu, überspringt das ungültige Feature und gibt einen Bericht aus.

using System;
using System.IO;
using Aspose.Gis;
using Aspose.Gis.Formats.Kml;
using Aspose.Gis.Operations;
using Aspose.Gis.SpatialReferencing;

namespace ShapefileTransformationErrors
{
    internal class Program
    {
        private static void Main()
        {
            string sourcePath = Path.Combine("data", "light-traffics.shp");
            string outputFolder = "output";
            Directory.CreateDirectory(outputFolder);

// -----------------------------------------------------------------
            // Run 1: default behavior. The first failed transformation aborts
            // the whole conversion with a TransformationException.
            // -----------------------------------------------------------------
            string failFastPath = Path.Combine(outputFolder, "fail-fast.kml");
            try
            {
                VectorLayer.Convert(sourcePath, Drivers.Shapefile, failFastPath, Drivers.Kml);
                Console.WriteLine("Default conversion finished without transformation errors.");
            }
            catch (TransformationException ex)
            {
                Console.WriteLine($"Default conversion aborted: {ex.Message}");
                Console.WriteLine($"Failing coordinate: ({ex.X}, {ex.Y}, {ex.Z})");
            }

// -----------------------------------------------------------------
            // Run 2: error-tolerant conversion. Invalid features are skipped
            // and recorded in the collector; valid features are written.
            // -----------------------------------------------------------------
            string destinationPath = Path.Combine(outputFolder, "light-traffics.kml");

var errors = new OperationErrorCollector();
            var options = new ConversionOptions
            {
                DestinationSpatialReferenceSystem = SpatialReferenceSystem.Wgs84,
                DestinationDriverOptions = new KmlOptions
                {
                    ErrorCollector = errors
                }
            };

VectorLayer.Convert(sourcePath, Drivers.Shapefile, destinationPath, Drivers.Kml, options);

// Report every skipped feature so the source data can be repaired.
            if (errors.HasErrors)
            {
                Console.WriteLine($"Conversion completed with {errors.Count} skipped feature(s):");

foreach (var error in errors.Errors)
                {
                    if (error is TransformationError transformationError)
                    {
                        Console.WriteLine(
                            $"  Feature #{transformationError.FeatureIndex} at " +
                            $"({transformationError.X}, {transformationError.Y}, {transformationError.Z}): {error.Message}");
                    }
                    else
                    {
                        Console.WriteLine($"  {error.Message}");
                    }
                }
            }
            else
            {
                Console.WriteLine("Conversion completed with no errors.");
            }

// Verify the output file.
            using (var layer = VectorLayer.Open(destinationPath, Drivers.Kml))
            {
                Console.WriteLine($"Features written to KML: {layer.Count}");
            }
        }
    }
}

7. Häufige Fallstricke und wie man sie vermeidet

Kostenlose Lizenz erhalten

Sie können eine temporäre kostenlose Lizenz für Aspose.GIS von der Aspose‑Temporärlizenz‑Seite erhalten: https://purchase.aspose.com/temporary-license/

Kostenlose zusätzliche Ressourcen

• Dokumentation: https://docs.aspose.com/gis/net/
• API-Referenz: https://reference.aspose.com/gis/net/
• Kostenlose Web‑Apps: https://products.aspose.app/gis/family

Fazit

Eine TransformationException während der Shapefile‑Konvertierung bedeutet in der Regel, dass eine kleine Anzahl von Datensätzen Koordinaten enthält, die nicht transformiert werden können, z. B. Platzhalterwerte, Zahlen außerhalb des zulässigen Bereichs oder Daten, die nicht mit ihrer .prj‑Datei übereinstimmen. Die Behebung in C# erfolgt in zwei Schritten: Ein OperationErrorCollector anhängen, damit Aspose.GIS for .NET ungültige Features überspringt und die Konvertierung abschließt, und anschließend die gesammelten Feature‑Indizes und Koordinaten verwenden, um die Quelldaten zu reparieren. Das Ergebnis ist eine Pipeline, die weiterhin gültige Ausgaben liefert, während harte Fehler in umsetzbare Datenqualitätsberichte umgewandelt werden.

FAQs

1. Warum tritt TransformationException beim Konvertieren einer Shapefile auf?
   Sie tritt auf, wenn ein Koordinatenwert nicht vom Quellkoordinatensystem in das Zielkoordinatensystem transformiert werden kann. Häufige Ursachen sind Platzhalter‑Werte wie „no data“, Koordinaten außerhalb des gültigen Bereichs ihres Koordinatensystems, eine .prj‑Datei, die nicht zu den tatsächlichen Daten passt, und beschädigte Geometrierecords.

2. Was passiert standardmäßig, wenn ein Koordinatensatz nicht transformiert werden kann? VectorLayer.Convert wirft eine TransformationException und die Konvertierung wird abgebrochen. Ab Version 26.6 gibt die Ausnahme außerdem die Werte X, Y und Z der fehlerhaften Koordinate zurück.

3. Welche Version von Aspose.GIS for .NET unterstützt OperationErrorCollector? OperationErrorCollector und die DriverOptions.ErrorCollector-Eigenschaft wurden in Aspose.GIS for .NET 26.6 eingeführt. Frühere Versionen enthalten sie nicht.

4. Repariert OperationErrorCollector ungültige Koordinaten? Nein. Es überspringt die Features, die bei der Transformation fehlschlagen, und protokolliert sie, sodass die Ausgabe nur gültige Features enthält. Verwenden Sie den gemeldeten Feature‑Index und die Koordinaten, um die fehlerhaften Datensätze in den Quelldaten zu korrigieren oder zu entfernen.

5. Kann ich OperationErrorCollector mit anderen Ausgabeformaten als KML verwenden? ErrorCollector ist in der Basisklasse DriverOptions definiert, sodass jede Treiberoptionsklasse sie bereitstellt. Dokumentierte Beispiele decken KML- und MapInfo‑TAB-Ziele ab; testen Sie das Verhalten mit Ihrem eigenen Zieltreiber, bevor Sie sich in der Produktion darauf verlassen.

6. Welche Details enthält jeder gesammelte Fehler? Jeder OperationError liefert eine Message und die zugrunde liegende Exception. Transformationsfehler werden als TransformationError‑Objekte gemeldet, die den FeatureIndex sowie die Werte X, Y und Z der fehlerhaften Koordinate hinzufügen.

7. Wie kann ich feststellen, ob eine Konvertierung ohne Fehler abgeschlossen wurde? Überprüfen Sie die HasErrors- oder Count-Eigenschaft des Collectors, nachdem VectorLayer.Convert zurückgekehrt ist. Eine Konvertierung, die ohne Ausnahme beendet wird, kann dennoch übersprungene Features haben.

Mehr lesen

• Shapefile in KML in C# konvertieren
• GEOJSON zu Topojson-Konvertierung in .NET: Beispielanleitung