dotnet / dotnet/docs

Inconsistent Embedded Resource Naming Rules Between Directory Names and Filenames in MSBuild

Open
#47,101 5 comments 1 reaction 0 assignees View on GitHub
:watch: Not Triaged
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
19h 10m
Merged PRs (30d)
268

Description

### Describe the issue or suggestion

**Description**
I've observed inconsistent behavior in MSBuild's embedded resource naming rules that requires clarification. The naming pattern appears as:
`[RootNamespace] + [DirectoryPath(modified)] + [Filename(original)]`

Where:
- **Root namespace** is preserved as-is (`PosPal.HybridAppAssembly` in our case)
- **Directory names** have invalid characters replaced with underscores (`-` → `_`, spaces → `_`)
- **Filenames** preserve all original characters including hyphens, spaces, and special symbols

**Evidence from Actual Build Output**
This resource list was obtained via `GetManifestResourceNames()` (screenshot attached):
```
PosPal.HybridAppAssembly.website.H5_demo.images.ad-01.jpg
PosPal.HybridAppAssembly.website.H5_demo.images.ad-02.jpg
PosPal.HybridAppAssembly.website.H5_demo.images.ad-03.jpg
PosPal.HybridAppAssembly.website.H5_demo.images.ad-04.jpg
PosPal.HybridAppAssembly.website.H5_demo.images.bag.jpg
PosPal.HybridAppAssembly.website.H5_demo.images.borgas.jpg
PosPal.HybridAppAssembly.website.H5_demo.login.html
```

Key observations:
1. Directory `H5-demo` becomes `H5_demo` (hyphen replaced with underscore)
2. Filenames preserve hyphens (`ad-04.jpg` remains unchanged)
3. All path separators become dots (`images\ad-04.jpg` → `images.ad-04.jpg`)

**Requested Information**
1. Is this directory-vs-filename difference in character replacement **officially documented** behavior?
2. What is the **technical rationale** for treating directory names and filenames differently?
3. Are there any **customization options** to:
- Disable directory name character replacement?
- Apply consistent rules to both directories and files?
4. How should we handle **resource retrieval** when filenames contain spaces/special characters?
(Current workaround requires exact match with original characters)
5. Is this behavior **consistent** across:
- Different MSBuild versions?
- .NET Framework vs .NET Core/5+?
- Windows vs Linux/macOS builds?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.