From 390786530791429c337ff786efb096a581104a62 Mon Sep 17 00:00:00 2001 From: Julian Verdurmen <5808377+304NotModified@users.noreply.github.com> Date: Tue, 8 Sep 2026 21:36:06 +0200 Subject: [PATCH] reorderd readme --- README.md | 155 +++++++++++++++++++++++++++--------------------------- 1 file changed, 78 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 9bbb3fc..7fe70cd 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,84 @@ slnx-validator "MySolution.slnx, src\*.slnx, other\" Exit code `0` means everything is valid. Exit code `1` means one or more errors were found. +## Example output + +### All valid ✅ + +```powershell +slnx-validator MySolution.slnx +``` + +``` +[OK] MySolution.slnx +``` + +### Errors found ❌ + +```powershell +slnx-validator MySolution.slnx +``` + +``` +[FAIL] MySolution.slnx + +MySolution.slnx + - line 5: [SLNX013] The element 'Folder' in namespace '...' has invalid child element 'Folder'. List of possible elements expected: 'Project'. + - line 12: [SLNX011] File not found: docs\CONTRIBUTING.md +``` + +### Multiple files — mixed results + +```powershell +slnx-validator src\ +``` + +``` +[OK] src\Frontend.slnx +[FAIL] src\Backend.slnx + +src\Backend.slnx + - line 4: [SLNX011] File not found: docs\CONTRIBUTING.md + - line 8: [SLNX012] Wildcard patterns are not supported in file paths: docs\*.md +``` + +## What is validated + +This tool checks what `dotnet` / MSBuild / Visual Studio does **not** validate by default: + +- **XSD schema validation** — verifies that the `.slnx` file conforms to the [official Microsoft schema](https://github.com/microsoft/vs-solutionpersistence/blob/main/src/Microsoft.VisualStudio.SolutionPersistence/Serializer/Xml/Slnx.xsd). + Visual Studio silently accepts certain invalid constructs without showing any error — for example, a `` nested inside another `` (see [`examples/invalid-xsd.slnx`](examples/invalid-xsd.slnx)). +- **Solution folder file existence** — checks that every `` listed inside a `` actually exists on disk. +- **Wildcard usage** — `.slnx` does not support wildcard patterns. Visual Studio silently accepts them but simply ignores the entries, so your files appear to be listed but are never actually resolved. `slnx-validator` catches this in `` entries (see [`examples/invalid-wildcard.slnx`](examples/invalid-wildcard.slnx)): + + ```xml + + + + + ``` + + > Wildcard support is a [known open request](https://github.com/dotnet/sdk/issues/41465) that was closed as not planned. + +The following are **intentionally out of scope** because the toolchain already handles them: + +- Project file existence (``) — `dotnet build` / MSBuild already reports missing project files. + +## Error codes + +| Code | Name | Description | +|------|------|-------------| +| `SLNX001` | `FileNotFound` | The input `.slnx` file does not exist. | +| `SLNX002` | `InvalidExtension` | The input file does not have a `.slnx` extension. | +| `SLNX003` | `NotATextFile` | The file is binary and cannot be parsed as XML. | +| `SLNX010` | `InvalidXml` | The file is not valid XML (see [`examples/invalid-not-xml.slnx`](examples/invalid-not-xml.slnx)). | +| `SLNX011` | `ReferencedFileNotFound` | A file referenced in `` does not exist on disk. | +| `SLNX012` | `InvalidWildcardUsage` | A `` contains a wildcard pattern (see [`examples/invalid-wildcard.slnx`](examples/invalid-wildcard.slnx)). | +| `SLNX013` | `XsdViolation` | The XML structure violates the schema, e.g. `` inside `` (see [`examples/invalid-xsd.slnx`](examples/invalid-xsd.slnx)). | +| `SLNX020` | `RequiredFileDoesntExistOnSystem` | A `--required-files` pattern matched no files on the file system. | +| `SLNX021` | `RequiredFileNotReferencedInSolution` | A `--required-files` matched file exists on disk but is not referenced as a `` element in the solution. | + + ## Options ### `--sonarqube-report-file ` @@ -329,83 +407,6 @@ Example SARIF output: } ``` -## Example output - -### All valid ✅ - -```powershell -slnx-validator MySolution.slnx -``` - -``` -[OK] MySolution.slnx -``` - -### Errors found ❌ - -```powershell -slnx-validator MySolution.slnx -``` - -``` -[FAIL] MySolution.slnx - -MySolution.slnx - - line 5: [SLNX013] The element 'Folder' in namespace '...' has invalid child element 'Folder'. List of possible elements expected: 'Project'. - - line 12: [SLNX011] File not found: docs\CONTRIBUTING.md -``` - -### Multiple files — mixed results - -```powershell -slnx-validator src\ -``` - -``` -[OK] src\Frontend.slnx -[FAIL] src\Backend.slnx - -src\Backend.slnx - - line 4: [SLNX011] File not found: docs\CONTRIBUTING.md - - line 8: [SLNX012] Wildcard patterns are not supported in file paths: docs\*.md -``` - -## What is validated - -This tool checks what `dotnet` / MSBuild / Visual Studio does **not** validate by default: - -- **XSD schema validation** — verifies that the `.slnx` file conforms to the [official Microsoft schema](https://github.com/microsoft/vs-solutionpersistence/blob/main/src/Microsoft.VisualStudio.SolutionPersistence/Serializer/Xml/Slnx.xsd). - Visual Studio silently accepts certain invalid constructs without showing any error — for example, a `` nested inside another `` (see [`examples/invalid-xsd.slnx`](examples/invalid-xsd.slnx)). -- **Solution folder file existence** — checks that every `` listed inside a `` actually exists on disk. -- **Wildcard usage** — `.slnx` does not support wildcard patterns. Visual Studio silently accepts them but simply ignores the entries, so your files appear to be listed but are never actually resolved. `slnx-validator` catches this in `` entries (see [`examples/invalid-wildcard.slnx`](examples/invalid-wildcard.slnx)): - - ```xml - - - - - ``` - - > Wildcard support is a [known open request](https://github.com/dotnet/sdk/issues/41465) that was closed as not planned. - -The following are **intentionally out of scope** because the toolchain already handles them: - -- Project file existence (``) — `dotnet build` / MSBuild already reports missing project files. - -## Error codes - -| Code | Name | Description | -|------|------|-------------| -| `SLNX001` | `FileNotFound` | The input `.slnx` file does not exist. | -| `SLNX002` | `InvalidExtension` | The input file does not have a `.slnx` extension. | -| `SLNX003` | `NotATextFile` | The file is binary and cannot be parsed as XML. | -| `SLNX010` | `InvalidXml` | The file is not valid XML (see [`examples/invalid-not-xml.slnx`](examples/invalid-not-xml.slnx)). | -| `SLNX011` | `ReferencedFileNotFound` | A file referenced in `` does not exist on disk. | -| `SLNX012` | `InvalidWildcardUsage` | A `` contains a wildcard pattern (see [`examples/invalid-wildcard.slnx`](examples/invalid-wildcard.slnx)). | -| `SLNX013` | `XsdViolation` | The XML structure violates the schema, e.g. `` inside `` (see [`examples/invalid-xsd.slnx`](examples/invalid-xsd.slnx)). | -| `SLNX020` | `RequiredFileDoesntExistOnSystem` | A `--required-files` pattern matched no files on the file system. | -| `SLNX021` | `RequiredFileNotReferencedInSolution` | A `--required-files` matched file exists on disk but is not referenced as a `` element in the solution. | - ## XSD Schema Microsoft doesn't provide much documentation for the `.slnx` format, but there is an XSD schema in the official `vs-solutionpersistence` repository — and it's enough to catch real structural problems before they cause trouble: