108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# Dokumentation
|
|
|
|
## Ziel
|
|
|
|
BinaryConverter ist fuer Umgebungen gedacht, in denen eine binaere Datei nicht direkt uebertragen werden kann, Text per Copy & Paste aber moeglich ist. Die Anwendung erzeugt deshalb eine robuste Textdarstellung und prueft beim Rueckweg, ob die rekonstruierte Datei bytegenau passt.
|
|
|
|
## Dateiformat
|
|
|
|
Das Transferfile besteht aus Kommentar-Metadaten, einem Beginn-Marker, Base64-Nutzdaten und einem Ende-Marker.
|
|
|
|
```text
|
|
# BinaryConverter-Format: 1
|
|
# Encoding: Base64
|
|
# SourceFileNameBase64: <UTF-8-Dateiname als Base64>
|
|
# SourceLength: <Bytes>
|
|
# SHA256: <Hex-Hash>
|
|
# CreatedUtc: <ISO-8601>
|
|
# LineLength: 76
|
|
-----BEGIN BINARYCONVERTER BASE64-----
|
|
<Base64-Daten>
|
|
-----END BINARYCONVERTER BASE64-----
|
|
```
|
|
|
|
Die Base64-Nutzdaten werden mit 76 Zeichen pro Zeile geschrieben. Das ist bewusst konservativ, damit Zeilenumbrueche in vielen Editoren, Konsolen und Remote-Sessions gut handhabbar bleiben.
|
|
|
|
## Integritaet
|
|
|
|
Beim Encode wird die Eingabedatei zuerst einmal gelesen, um SHA-256 zu berechnen. Danach wird sie in einem zweiten Durchlauf als Base64 geschrieben. Der zweite Durchlauf vermeidet, dass grosse Dateien komplett in den Speicher geladen werden.
|
|
|
|
Bei Encode und Decode wird zuerst in eine temporaere Datei geschrieben. Erst nach erfolgreicher Verarbeitung wird diese temporaere Datei auf den finalen Ausgabepfad verschoben beziehungsweise ersetzt. Beim Decode passiert das erst nach erfolgreicher Laengen- und SHA-256-Pruefung. Bei Fehlern wird die temporaere Datei geloescht.
|
|
|
|
## Speicherverhalten
|
|
|
|
Die Anwendung arbeitet streaming-basiert:
|
|
|
|
- Eingabe wird blockweise gelesen.
|
|
- Base64 wird blockweise geschrieben beziehungsweise dekodiert.
|
|
- Es wird nicht die komplette Eingabe- oder Ausgabedatei in den Arbeitsspeicher geladen.
|
|
|
|
Beim Decode wird ein kleiner Base64-Puffer verwendet, um auch unguenstig umgebrochene Base64-Zeilen verarbeiten zu koennen.
|
|
|
|
## Fehlerverhalten
|
|
|
|
Typische Fehler werden mit Exitcode `1` beendet:
|
|
|
|
- Eingabedatei fehlt.
|
|
- Ausgabedatei existiert bereits und `-Force` wurde nicht gesetzt.
|
|
- Transferfile ist unvollstaendig, zum Beispiel fehlender Ende-Marker.
|
|
- Base64-Inhalt ist ungueltig.
|
|
- Dekodierte Laenge passt nicht zur Metadatenlaenge.
|
|
- SHA-256 passt nicht zum Metadatenhash.
|
|
|
|
Argumentfehler werden mit Exitcode `2` beendet. Erfolgreiche Ausfuehrung endet mit Exitcode `0`.
|
|
|
|
## Logging
|
|
|
|
Standardmaessig schreibt BinaryConverter auf die Konsole:
|
|
|
|
- Version und Operation
|
|
- Eingabe- und Ausgabepfad
|
|
- Fortschritt und Durchsatz
|
|
- berechnete beziehungsweise gepruefte SHA-256-Summe
|
|
- finale Dateigroessen
|
|
|
|
Mit `-Log <Datei>` werden dieselben Informationen zusaetzlich in eine Logdatei geschrieben.
|
|
|
|
## Beispiele
|
|
|
|
Datei fuer Transfer vorbereiten:
|
|
|
|
```powershell
|
|
.\BinaryConverter.exe -Encode C:\temp\PowerShell.exe -Output C:\temp\Out.txt -Log C:\temp\encode.log
|
|
```
|
|
|
|
Auf dem Zielhost zurueckwandeln:
|
|
|
|
```powershell
|
|
.\BinaryConverter.exe -Decode C:\temp\Out.txt C:\temp\PowerShell.exe -Log C:\temp\decode.log
|
|
```
|
|
|
|
Bereits vorhandene Zieldatei ersetzen:
|
|
|
|
```powershell
|
|
.\BinaryConverter.exe -Decode C:\temp\Out.txt C:\temp\PowerShell.exe -Force
|
|
```
|
|
|
|
## Repository-Struktur
|
|
|
|
```text
|
|
BinaryConverter/
|
|
BinaryConverter.sln
|
|
BinaryConverter/
|
|
BinaryConverter.csproj
|
|
App.config
|
|
Program.cs
|
|
Properties/
|
|
AssemblyInfo.cs
|
|
.editorconfig
|
|
.gitattributes
|
|
.gitignore
|
|
Dokumentation.md
|
|
Readme.md
|
|
```
|
|
|
|
## Gitea-Hinweise
|
|
|
|
Das Repository enthaelt keine Build-Artefakte. `bin/`, `obj/`, Visual-Studio-Userdateien, Logs und temporaere Dateien sind ueber `.gitignore` ausgeschlossen.
|