58 lines
4.2 KiB
Markdown
58 lines
4.2 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/Modules/Database/DatabaseMigrationScripts/EmbeddedResource.cs
|
||
generated_at: "2026-04-16T04:34:42.810625+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "ab2d5b23dd090ece"
|
||
---
|
||
|
||
# DatabaseMigrationScripts
|
||
|
||
### **Purpose**
|
||
This module provides utilities for reading embedded resources (e.g., SQL migration scripts) from a .NET assembly’s manifest resources. It exists to simplify access to versioned, compiled-in migration files without requiring external file system dependencies, enabling reliable deployment of database schema changes across environments.
|
||
|
||
---
|
||
|
||
### **Public Interface**
|
||
|
||
- **`static StreamReader GetStream(Assembly assembly, string name)`**
|
||
Searches the manifest resources of the given `assembly` for a resource whose name *ends with* `name` (case-sensitive substring match), and returns a `StreamReader` for the first match. Returns `null` if no matching resource is found.
|
||
*Note: Caller is responsible for disposing the `StreamReader`.*
|
||
|
||
- **`static string GetString(Assembly assembly, string name)`**
|
||
Reads the full content of the resource matching `name` (via `GetStream`) from the specified `assembly` and returns it as a `string`. Closes the `StreamReader` internally. Returns `null` if no matching resource is found.
|
||
|
||
- **`static string GetString(string name)`**
|
||
Overload of `GetString` that uses the assembly containing the `EmbeddedResource` type itself (`typeof(EmbeddedResource).Assembly`) as the source. Behaves identically to `GetString(assembly, name)` otherwise.
|
||
|
||
---
|
||
|
||
### **Invariants**
|
||
- Resource matching is performed via `EndsWith(name)` on the full manifest resource name (e.g., `"MyApp.Migrations.V1_0_0.sql"` matches for `name = "V1_0_0.sql"`).
|
||
- Only the *first* matching resource (by enumeration order) is used—no error is raised if multiple resources match.
|
||
- `GetString(Assembly, string)` and `GetString(string)` return `null` if no matching resource exists (not an exception).
|
||
- The `StreamReader` returned by `GetStream` must be explicitly closed/disposed by the caller to avoid resource leaks.
|
||
- `GetString` methods assume the resource content is text-encoded (UTF-8 or system default encoding, per `StreamReader` default behavior).
|
||
|
||
---
|
||
|
||
### **Dependencies**
|
||
- **Depends on**:
|
||
- `System.IO` (`StreamReader`, `Stream`)
|
||
- `System.Reflection.Assembly` (for `GetManifestResourceNames`, `GetManifestResourceStream`)
|
||
- **Depended on by**:
|
||
- Presumably database migration orchestration logic (e.g., a `MigrationRunner` class) that loads `.sql` files from embedded resources.
|
||
- *Inferred*: Other types in the `DatabaseMigrationScripts` namespace (not visible here) likely consume `EmbeddedResource` to retrieve migration scripts.
|
||
|
||
---
|
||
|
||
### **Gotchas**
|
||
- **Substring matching is ambiguous**: A request for `"V1.sql"` could match `"V1.sql"`, `"Old/V1.sql"`, or `"Backup_V1.sql"`—only the first match in `GetManifestResourceNames()` order is used. This may cause unexpected behavior if resource naming is not strictly controlled.
|
||
- **No encoding specification**: `StreamReader` uses default encoding (typically UTF-8 without BOM on .NET Core/.NET 5+, but system default on .NET Framework), which may cause issues if migration files contain non-ASCII characters and were authored with a different encoding.
|
||
- **Resource enumeration order is undefined**: `GetManifestResourceNames()` does not guarantee consistent ordering across builds or platforms, so multiple matching resources may yield non-deterministic results.
|
||
- **No validation of resource existence before `ReadToEnd()`**: If `GetStream` returns `null`, `GetString` will throw a `NullReferenceException` when calling `sr.ReadToEnd()`. *This is a critical bug*: `GetString(Assembly, string)` lacks null-checking on `sr`.
|
||
- **`EmbeddedResource()` constructor is private but unused**: The class is never instantiated (all members are static), but the empty constructor serves no functional purpose.
|
||
- **No support for binary resources**: Designed exclusively for text-based resources; binary files would require a different approach.
|
||
|
||
*Note: The `NullReferenceException` risk in `GetString(Assembly, string)` when `GetStream` returns `null` is a likely source of runtime failures and should be addressed.* |