How do source files, content files and embedded resources work in a .NET build, and how do you read an embedded resource at run time?

1. How files flow through the build

project folder
|-- Program.cs              -> Compile          -> csc -> Orders.dll (IL)
|-- Sql/CreateOrders.sql    -> EmbeddedResource -> csc /resource -> inside Orders.dll
|-- Strings.resx            -> EmbeddedResource -> GenerateResource -> Orders.dll (neutral culture)
|-- Strings.en-AU.resx      -> EmbeddedResource -> GenerateResource -> en-AU/Orders.resources.dll (satellite)
|-- data/postcodes.csv      -> None + CopyToOutputDirectory -> bin/.../data/postcodes.csv
|-- wwwroot/site.css        -> Content (Web SDK) -> bin/... and publish/wwwroot/
`-- notes.md                -> None (no metadata) -> nowhere

Run time:
  typeof(X).Assembly.GetManifestResourceStream("Orders.Data.Sql.CreateOrders.sql")
  File.OpenRead(Path.Combine(AppContext.BaseDirectory, "data", "postcodes.csv"))

Every file in the project folder becomes some item, because SDK-style projects glob by default. The item type decides what happens to it.

2. Item types and their metadata

Copy metadata

CopyToOutputDirectory controls bin/; CopyToPublishDirectory controls publish/. Files copied to the output are normally published too.

Files outside the project folder

<ItemGroup>
  <None Include="..\..\shared\countries.json" Link="data\countries.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Link sets where the file appears in the project tree and in the output.

Copied files flow to referencing projects

Files a project copies to its output are also copied into the output of projects that reference it. A test project referencing Orders.Reporting gets data/postcodes.csv too. That's usually what you want, but it can surprise you when two referenced projects copy files with the same relative path: the last one copied wins.

3. Embedded resource names

Without LogicalName, the manifest name is built like this:

RootNamespace   +  relative folder path (separators -> dots)  +  file name
Orders.Data     .  Sql                                          .  CreateOrders.sql
=> "Orders.Data.Sql.CreateOrders.sql"

The fastest debugging step for a null stream:

foreach (var name in typeof(Program).Assembly.GetManifestResourceNames())
    Console.WriteLine(name);

4. Reading resources

The stream is a view over the loaded assembly image. The real cost is what you build from it, so read once and cache:

private static readonly Lazy<string> ReceiptTemplate = new(() =>
{
    using var stream = typeof(ReceiptRenderer).Assembly.GetManifestResourceStream("Orders.Templates.Receipt")
        ?? throw new InvalidOperationException("Receipt template not embedded.");
    using var reader = new StreamReader(stream);
    return reader.ReadToEnd();
});

5. .resx, satellites and localisation

Strings.resx         -> neutral strings, inside Orders.dll
Strings.en-AU.resx   -> en-AU/Orders.resources.dll
Strings.fr.resx      -> fr/Orders.resources.dll

ResourceManager looks up: en-AU -> en -> neutral (inside the main assembly)

• Set NeutralResourcesLanguage (for example en-AU) so lookups for the default culture don't search for a satellite that doesn't exist.
• Packages often ship satellites for dozens of languages. <SatelliteResourceLanguages>en</SatelliteResourceLanguages> keeps only the ones you need, which shrinks the output and container image noticeably.
• In ASP.NET Core, IStringLocalizer<T> with AddLocalization() and request localisation middleware chooses the culture per request.

6. Single-file, trimming and AOT

Use AppContext.BaseDirectory to locate copied files in every shape; Assembly.Location and Directory.GetCurrentDirectory() are wrong for single-file apps and for services started from another folder.

7. Embed or copy?

8. Performance

• Each embedded resource adds to the DLL, the container image and every deployment's download, even if the code that reads it never runs.
• Reading is cheap; materialising (strings, parsed JSON, compiled templates) is the cost. Cache the result.
• CopyToOutputDirectory="Always" makes Visual Studio treat the project as always out of date, so it rebuilds on every F5.
• Trim unused satellite languages with SatelliteResourceLanguages.

9. Security

• Anyone with the DLL can list and extract embedded resources (ILSpy shows them in seconds). Never embed secrets, private keys, certificates or connection strings.
• Copied configuration files are just as visible on disk; secrets belong in Key Vault, managed identity or environment variables injected at run time.
• Templates that render user data (emails, receipts) still need proper encoding; embedding doesn't make them safe.

10. .NET 11 awareness

Resource handling is stable. Watch the .NET 11 SDK notes for changes to single-file and AOT publishing defaults that affect copied files. Keep production on .NET 10 until you've tested an upgrade.

11. Try it yourself

1. Add Sql/Hello.sql to a console project and mark it as EmbeddedResource.
2. Print typeof(Program).Assembly.GetManifestResourceNames() and note the default name.
3. Rename the Sql folder to Scripts and print the names again.
4. Add LogicalName="Demo.Sql.%(Filename)", update the code, and rename the folder back; the name no longer changes.
5. Add data/info.txt with CopyToOutputDirectory="PreserveNewest", build, and read it with AppContext.BaseDirectory.
6. Reference the console project from a test project and check that data/info.txt appears in the test output.
7. Publish with -p:PublishSingleFile=true -r linux-x64 and compare Assembly.Location with AppContext.BaseDirectory.
8. Add a package with many satellite languages (for example Humanizer), build, count the culture folders, then set SatelliteResourceLanguages to en and count again.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <RootNamespace>Orders.Reporting</RootNamespace>
  </PropertyGroup>

  <ItemGroup>
    <EmbeddedResource Include="Sql/**/*.sql" LogicalName="Orders.Reporting.Sql.%(Filename)" />
    <None Update="data/postcodes.csv" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>
</Project>

using System.Reflection;

namespace Orders.Reporting;

public static class SqlScripts
{
    private static readonly Assembly Assembly = typeof(SqlScripts).Assembly;

    public static async Task<string> LoadAsync(string name, CancellationToken cancellationToken = default)
    {
        var resourceName = $"Orders.Reporting.Sql.{name}";
        await using var stream = Assembly.GetManifestResourceStream(resourceName)
            ?? throw new InvalidOperationException(
                $"Embedded SQL '{resourceName}' not found. Available: {string.Join(", ", Assembly.GetManifestResourceNames())}");
        using var reader = new StreamReader(stream);
        return await reader.ReadToEndAsync(cancellationToken);
    }
}

// A test that fails if a script is renamed or not embedded
public class SqlScriptsTests
{
    [Theory]
    [InlineData("MonthlyGstSummary")]
    [InlineData("OutstandingInvoices")]
    public async Task Script_is_embedded(string name) =>
        Assert.False(string.IsNullOrWhiteSpace(await SqlScripts.LoadAsync(name)));
}

%(Filename) is item metadata without the extension, so Sql/MonthlyGstSummary.sql becomes Orders.Reporting.Sql.MonthlyGstSummary.