Direkt zum Hauptinhalt

ExcelDataImporter - Anwendungsdokumentation

Anwendungsdokumentation

🎯 Übersicht

ExcelDataImporter ist ein automatisierter Importdienst für die Übernahme von Daten aus Excel-Dateien in Microsoft SQL Server Datenbanken. Der Dienst kann als Docker-Container oder als Windows-Service betrieben werden.

Hauptmerkmale

  • ✅ Automatisierte Datenübernahme: Cron-basierte Planung für wiederkehrende Importprozesse
  • ✅ Flexible Dateibeobachtung: Überwacht konfigurierbare Ordner mit Wildcard-Mustern
  • ✅ Dynamische Tabellenerstellung: Erstellt Datenbank-Tabellen und -Spalten automatisch
  • ✅ Multi-Format-Unterstützung: Verarbeitet Excel-Dateien in den Formaten .xlsx und .xls
  • ✅ Subfolder-Unterstützung: Rekursive Verzeichnissuche bei Bedarf
  • ✅ Flexible Deployment-Optionen: Docker-Container oder Windows-Service

💻 Systemvoraussetzungen

Docker-Installation

  • Docker: Docker Engine 20.10+ oder Docker Desktop
  • Betriebssystem: Linux, Windows oder macOS mit Docker-Unterstützung
  • Datenbank: Microsoft SQL Server 2016+ (erreichbar vom Container)
  • Speicher: Mindestens 512 MB RAM für den Container
  • Netzwerk: Zugriff auf SQL Server und Excel-Datei-Ordner

Windows-Service-Installation

  • Betriebssystem: Windows Server 2016+ / Windows 10+
  • .NET Runtime: .NET 10.0 oder höher
  • Datenbank: Microsoft SQL Server 2016+ (Express, Standard, Enterprise)
  • Speicher: Mindestens 512 MB RAM
  • Netzwerk: Zugriff auf SQL Server und zu überwachende Ordner

📦 Installation

Docker-Installation (Empfohlen)

Die Installation über Docker ist die empfohlene Methode für den Betrieb von ExcelDataImporter.

Schritt 1: Docker Image herunterladen

# Neueste Version von der GitHub Container Registry herunterladen
docker pull ghcr.io/css-edv-support/exceldataimporter:latest

Schritt 2: Konfigurationsdatei vorbereiten

Erstellen Sie eine appsettings.json Datei mit Ihrer Konfiguration (siehe Abschnitt Konfiguration).

Schritt 3: Container starten

# Mit Volume-Mapping für Konfiguration, Logs und Datenordner
docker run -d \
  --name exceldataimporter \
  -v /pfad/zur/appsettings.json:/app/appsettings.json:ro \
  -v /pfad/zu/logs:/app/Logs \
  -v /pfad/zu/daten:/data \
  ghcr.io/css-edv-support/exceldataimporter:latest

Hinweis: Passen Sie die Volume-Pfade an Ihre Umgebung an:

  • /pfad/zur/appsettings.json: Pfad zu Ihrer Konfigurationsdatei
  • /pfad/zu/logs: Verzeichnis für Log-Dateien
  • /pfad/zu/daten: Verzeichnis mit Excel-Dateien (z.B. /data/Import in der Config verwenden)

Schritt 4: Container-Status überprüfen

# Container-Status prüfen
docker ps | grep exceldataimporter

# Logs überwachen
docker logs -f exceldataimporter

Docker Compose (Alternative)

Erstellen Sie eine docker-compose.yml Datei:

version: '3.8'

services:
  exceldataimporter:
    image: ghcr.io/css-edv-support/exceldataimporter:latest
    container_name: exceldataimporter
    volumes:
      - ./appsettings.json:/app/appsettings.json:ro
      - ./logs:/app/Logs
      - ./data:/data
    environment:
      - ConnectionStrings__ConnectionString=Server=sqlserver;Database=ImportDB;User Id=sa;Password=YourPassword;TrustServerCertificate=True;
      # Optional: Umgebungsvariablen für einzelne Import-Jobs
    restart: unless-stopped

Starten Sie den Service:

docker-compose up -d

Windows-Service-Installation (Alternative)

Falls Docker nicht verfügbar ist, kann ExcelDataImporter auch als Windows-Service installiert werden. Die notwendigen Daten erhalten Sie auf Anfrage.

Schritt 1: Anwendung herunterladen

Schritt 2: Konfiguration anpassen

Bearbeiten Sie die Datei C:\Services\ExcelDataImporter\appsettings.json entsprechend Ihrer Anforderungen (siehe Abschnitt Konfiguration).

Schritt 3: Windows-Service erstellen

# PowerShell als Administrator ausführen
sc.exe create ExcelDataImporter binPath="C:\Services\ExcelDataImporter\ExcelDataImporter.exe" start=auto
sc.exe description ExcelDataImporter "Automatisierter Excel-Datenimport-Service"
sc.exe start ExcelDataImporter

Schritt 4: Service-Status überprüfen

# Service-Status prüfen
sc.exe query ExcelDataImporter

# Logs überprüfen
Get-Content C:\Services\ExcelDataImporter\Logs\log.txt -Tail 50 -Wait

Service entfernen

# Service stoppen und entfernen
sc.exe stop ExcelDataImporter
sc.exe delete ExcelDataImporter

⚙️ Konfiguration

Die Konfiguration erfolgt über die Datei appsettings.json. Bei Docker können alternativ auch Umgebungsvariablen verwendet werden.

Konfiguration über appsettings.json

Basis-Struktur

{
    "Serilog": {
        "MinimumLevel": "Information",
        "WriteTo": [
            {
                "Name": "Console"
            },
            {
                "Name": "File",
                "Args": {
                    "path": "Logs/log.txt",
                    "rollingInterval": "Day",
                    "retainedFileCountLimit": 7
                }
            }
        ]
    },
    "ImportJobs": [
        {
            "JobName": "DailyProductImport",
            "CronExpression": "0 2 * * *",
            "Pfad": "C:\\Import\\Products",
            "ExcelFilePattern": "Products_*.xlsx",
            "DestinationTable": "ProductData",
            "CreateDateOfImportColumn": true,
            "NameOfImportDateColumn": "ImportDate",
            "TruncateDestinationTable": true,
            "IncludeSubfolders": false,
            "ConnectionString": "Server=localhost;Database=ImportDB;User Id=sa;Password=YourPassword;TrustServerCertificate=True;"
        }
    ],
    "connectionStrings": {
        "ConnectionString": "Server=localhost;Database=ImportDB;User Id=sa;Password=YourPassword;TrustServerCertificate=True;"
    }
}

Import-Job-Parameter

Pflichtfelder:

Parameter Typ Beschreibung Beispiel
JobName string Eindeutiger Name des Import-Jobs "DailyProductImport"
Pfad string Quellverzeichnis für Excel-Dateien "C:\\Import\\Products" oder /data/Import
ExcelFilePattern string Suchmuster für Dateien (Wildcards erlaubt) "Products_*.xlsx"
DestinationTable string Ziel-Tabelle in der Datenbank "ProductData"

Optionale Felder:

Parameter Typ Standard Beschreibung
CronExpression string "* * * * *" Zeitplan (Format: Minute Stunde Tag Monat Wochentag)
CreateDateOfImportColumn bool false Erstellt eine Spalte für das Importdatum
NameOfImportDateColumn string null Name der Import-Datumsspalte
TruncateDestinationTable bool false Leert die Zieltabelle vor dem Import
ExcelFormat string "xlsx" Excel-Format: "xlsx" oder "xls"
RemoveRows int? null Anzahl der zu entfernenden Zeilen am Anfang
FillEmptyColumns int[]? null Spaltenindizes für Forward-Fill (0-basiert)
RemoveRowIfColumnIsEmpty int? null Entfernt Zeilen, wenn angegebene Spalte leer ist
IncludeSubfolders bool false Durchsucht Unterverzeichnisse
ConnectionString string? null Job-spezifischer Connection String (überschreibt global)

Cron-Ausdrücke

Cron-Ausdrücke definieren den Zeitplan für Import-Jobs. Format: Minute Stunde Tag Monat Wochentag

Häufige Beispiele:

Cron-Ausdruck Beschreibung
0 2 * * * Täglich um 2:00 Uhr
0 */4 * * * Alle 4 Stunden
0 6 * * 1-5 Werktags um 6:00 Uhr
30 14 1 * * Am ersten Tag des Monats um 14:30 Uhr
0 0 * * 0 Jeden Sonntag um Mitternacht

Hinweis: Nutzen Sie Online-Tools wie crontab.guru zur Validierung.

Connection Strings

Globaler Connection String (gilt für alle Jobs ohne eigenen Connection String):

"connectionStrings": {
    "ConnectionString": "Server=localhost;Database=ImportDB;User Id=sa;Password=YourPassword;TrustServerCertificate=True;"
}

Job-spezifischer Connection String (überschreibt den globalen):

{
    "JobName": "SpecialImport",
    "ConnectionString": "Server=server2;Database=SpecialDB;Integrated Security=True;",
    ...
}

Konfiguration über Umgebungsvariablen (Docker)

Bei Docker können Konfigurationswerte über Umgebungsvariablen gesetzt werden. Die Variablennamen verwenden dabei __ (doppelter Unterstrich) als Trennzeichen für die JSON-Hierarchie.

Beispiel: Connection String setzen

# Docker run
docker run -d \
  --name exceldataimporter \
  -e ConnectionStrings__ConnectionString="Server=sqlserver;Database=ImportDB;User Id=sa;Password=YourPassword;TrustServerCertificate=True;" \
  -v /pfad/zur/appsettings.json:/app/appsettings.json:ro \
  -v /pfad/zu/logs:/app/Logs \
  -v /pfad/zu/daten:/data \
  ghcr.io/css-edv-support/exceldataimporter:latest

Docker Compose mit Umgebungsvariablen

version: '3.8'

services:
  exceldataimporter:
    image: ghcr.io/css-edv-support/exceldataimporter:latest
    container_name: exceldataimporter
    volumes:
      - ./appsettings.json:/app/appsettings.json:ro
      - ./logs:/app/Logs
      - ./data:/data
    environment:
      # Connection String
      - ConnectionStrings__ConnectionString=Server=sqlserver;Database=ImportDB;User Id=sa;Password=YourPassword;TrustServerCertificate=True;
      
      # Logging Level (Optional)
      - Serilog__MinimumLevel=Information
      
    restart: unless-stopped

  # Optional: SQL Server Container
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrongPassword123!
      - MSSQL_PID=Express
    ports:
      - "1433:1433"
    volumes:
      - sqldata:/var/opt/mssql

volumes:
  sqldata:

Wichtige Umgebungsvariablen:

Variable Beschreibung Beispiel
ConnectionStrings__ConnectionString Datenbank-Verbindungszeichenfolge Server=...;Database=...
Serilog__MinimumLevel Log-Level Information, Debug, Warning

Hinweis: Die Konfiguration von Import-Jobs über Umgebungsvariablen ist komplex. Es wird empfohlen, die Jobs in der appsettings.json zu definieren und nur den Connection String über Umgebungsvariablen zu überschreiben.

Konfigurations-Beispiele

Beispiel 1: Einfacher täglicher Import

{
    "ImportJobs": [
        {
            "JobName": "DailySalesImport",
            "CronExpression": "0 6 * * *",
            "Pfad": "/data/Import/Sales",
            "ExcelFilePattern": "Sales_*.xlsx",
            "DestinationTable": "SalesData",
            "TruncateDestinationTable": true,
            "CreateDateOfImportColumn": true,
            "NameOfImportDateColumn": "ImportTimestamp"
        }
    ]
}

Beispiel 2: Import mit Datenbereinigung

{
    "ImportJobs": [
        {
            "JobName": "InventoryUpdate",
            "CronExpression": "0 * * * *",
            "Pfad": "/data/Inventory",
            "ExcelFilePattern": "inventory_*.xlsx",
            "DestinationTable": "Inventory",
            "TruncateDestinationTable": false,
            "RemoveRows": 2,
            "FillEmptyColumns": [0, 1, 3],
            "RemoveRowIfColumnIsEmpty": 0,
            "IncludeSubfolders": true
        }
    ]
}

Beispiel 3: Mehrere Import-Jobs

{
    "ImportJobs": [
        {
            "JobName": "MorningProductSync",
            "CronExpression": "0 6 * * *",
            "Pfad": "/data/Products",
            "ExcelFilePattern": "*.xlsx",
            "DestinationTable": "Products",
            "TruncateDestinationTable": true
        },
        {
            "JobName": "EveningCustomerSync",
            "CronExpression": "0 18 * * *",
            "Pfad": "/data/Customers",
            "ExcelFilePattern": "*.xlsx",
            "DestinationTable": "Customers",
            "TruncateDestinationTable": true
        }
    ]
}

🚀 Verwendung

Excel-Datei-Anforderungen

Unterstützte Formate

  • .xlsx (Office Open XML)
  • .xls (Excel 97-2003)

Dateistruktur

  • Erste Zeile: Wird standardmäßig als Spaltennamen verwendet
  • Datenzeilen: Ab der zweiten Zeile (anpassbar mit RemoveRows)
  • Mehrere Arbeitsblätter: Nur das erste Arbeitsblatt wird verarbeitet

Beispiel-Excel-Struktur

ProductID ProductName Category Price Stock
1001 Laptop Electronics 999.99 50
1002 Mouse Accessories 19.99 200
1003 Keyboard Accessories 49.99 150

Grundlegender Workflow

  1. Konfiguration erstellen: appsettings.json mit Import-Jobs konfigurieren
  2. Service starten: Als Docker-Container oder Windows-Service
  3. Dateien bereitstellen: Excel-Dateien in die konfigurierten Verzeichnisse legen
  4. Automatische Verarbeitung: Jobs werden gemäß Cron-Zeitplan ausgeführt
  5. Ergebnisse prüfen: Daten in der Datenbank überprüfen und Logs kontrollieren

Logs überwachen

Docker

# Container-Logs anzeigen
docker logs -f exceldataimporter

# Logs im Volume prüfen
tail -f /pfad/zu/logs/log.txt

Windows-Service

# Logs über PowerShell anzeigen
Get-Content C:\Services\ExcelDataImporter\Logs\log.txt -Tail 50 -Wait

# Event Viewer verwenden
Get-EventLog -LogName Application -Source ExcelImportService -Newest 20

Wichtige Log-Meldungen

Log-Meldung Bedeutung
Started ExcelImportService Service erfolgreich gestartet
Adding Job {JobName} Job wurde registriert
{Job} is working. Execution Count: {Count} Job wird ausgeführt
Importiere Datei {Datei} Datei wird verarbeitet
Daten wurden erfolgreich in {Tabelle} importiert Import erfolgreich
Fehler beim Importieren Import fehlgeschlagen - Details im Log

Erweiterte Features

Spaltenfüllung (FillEmptyColumns)

Füllt leere Zellen mit dem letzten nicht-leeren Wert in der Spalte.

Beispiel:

"FillEmptyColumns": [0, 2]

Dies füllt leere Zellen in den Spalten 0 und 2 mit dem jeweils vorherigen Wert auf.

Bedingte Zeilenentfernung (RemoveRowIfColumnIsEmpty)

Entfernt Zeilen, bei denen eine bestimmte Spalte leer ist.

Beispiel:

"RemoveRowIfColumnIsEmpty": 1

Entfernt alle Zeilen, bei denen die Spalte mit Index 1 leer ist.

Subfolder-Suche (IncludeSubfolders)

Durchsucht rekursiv alle Unterverzeichnisse nach Excel-Dateien.

Beispiel:

"IncludeSubfolders": true

📞 Support

Dokumentation

Kontakt

Bei Fragen oder Problemen wenden Sie sich bitte an CSS EDV-Support.

📝 Lizenz

© CSS EDV-Support – Interne Nutzung oder nach Rücksprache.

Keine Kommentare vorhanden

nach oben