PodNet.EmbeddedTexts 1.0.0

PodNet.EmbeddedTexts

A simple C# incremental code generator that allows for efficiently embedding text file content into your code.

Usage

1. Add the PodNet.EmbeddedTexts NuGet package to your .NET project.
2. Add some text files (can be code files, can be markdown, plain text etc.) to your project you want the contents of to be available to you at compile time. Mark the files as having a build action of AdditionalFile. The most straightforward way to do this is by editing the .csproj project file and adding a pattern in an <ItemGroup>:

   <ItemGroup>
     <AdditionalFiles Include="Files/**" />
   </ItemGroup>
   

   You can do the above for individual files as well if you so choose. In this case you can even use the Visual Studio Properties Window (<kbd>F4</kbd> by default, while a file is being selected in Solution Explorer) and set the Build action property of the file(s) to "C# analyzer additional file". Once you do, Visual Studio will edit your .csproj file accordingly.
3. Once you set this up, you'll immediately find a public static string Content { get; } property generated on a class in a namespace according to the structure of your project, which returns the string content of the file. So, if your root namespace for the project is MyProject, and you have an AdditionalFiles element in your project's Files/MyFile.txt file with content file contents, you'll be able to call:

   Console.WriteLine(Files.MyFile_txt.Content); // Writes: "file contents"
   

Additional configuration

The generator is on by default for every AdditionalFiles text file you have in your project, and will include the file contents in your compilation. If this is not your desired use-case, you have a few options.

Additionally, you can configure the name of the generated namespace and class for every piece of content.

[!NOTE]
It's imporant to mention that the below is standard configuration practice for MSBuild items. The MSBuild project files (like .csproj or Directory.build.props) define items in the children of ItemGroup elements. The AdditionalFiles element can be used by all modern source generators and are not specific to PodNet.EmbeddedTexts. One quirk of MSBuild items is that they can be Included individually or by globbing patterns, but the execution and parsing of these files is (mostly) sequential, so if you have any files Included by any patterns, you then have to Update them instead of Include-ing again.

Make the generator opt-in

Set the MSBuild property PodNetAutoEmbedAdditionalTexts to false to disable automatic generation for all AdditionalFiles. Then, for each file you wish to embed in the compilation, add a PodNet_EmbedText="true" attribute its AdditionalFiles item.

<Project>
  
  <PropertyGroup>
    
    <PodNetAutoEmbedAdditionalTexts>false</PodNetAutoEmbedAdditionalTexts>
  </PropertyGroup>
  <ItemGroup>
    
    <AdditionalFiles Include="Files/**" />

    
    <AdditionalFiles Update="Files/Embed/**" PodNet_EmbedText="true" />

    
    <AdditionalFiles Update="Files/Embed/.gitkeep" PodNet_EmbedText="false" />
  </ItemGroup>
</Project>

This is useful if you have any source generators enabled that work on text files you wish to not include in the compilation.

[!WARNING] Remember that including all text files in the compilation will essentially make your assemblies/executables larger by about the size of the file. The generated static class and property won't be loaded into memory until first being referenced, but this can incur a performance hit when embedding larger files.

Opt-out of generation for files or folders

Whether you have the generator automatically generating or not, you can explicitly opt-out of generation by setting PodNet_EmbedText="false".

<Project>
  
  <ItemGroup>
    
    <AdditionalFiles Include="Files/NoEmbed/**" PodNet_EmbedText="false" />
  </ItemGroup>
</Project>

Configuring the generated class name and namespace

You can set the PodNet_EmbedTextNamespace and PodNet_EmbedTextClassName properties on the items to override the default namespace and class name.

<Project>
  
  <ItemGroup>
    
    <AdditionalFiles Include="Files/My File.txt" PodNet_EmbedTextNamespace="OtherNamespace" PodNet_EmbedTextClassName="MyFileTXT" />
  </ItemGroup>
</Project>

The above results in: OtherNamespace.MyFileTXT.Content being the property that holds the file content.

Advanced parameterization

Don't be shy to use MSBuild properties, well-known metadata and such to configure the generator.

<AdditionalFiles Include="@(Compile)" PodNet_EmbedTextNamespace="$(RootNamespace).CompiledFiles" PodNet_EmbedTextClassName="%(Filename)" />

The above includes all .cs files (and other files that are at that point included in the compilation) into the source itself, in the MyProject.CompiledFiles namespace, with the class name being that of the filename without the extension.

Contributing and Support

This project is intended to be widely usable, but no warranties are provided. If you want to contact us, feel free to do so in the repo's [Discussions], at our website at podnet.hu, or find us anywhere from LinkedIn and Patreon to Meetup, YouTube or X.

Any kinds of contributions from issues to PRs and open discussions are welcome!

Don't forget to give us a ⭐ if you like this repo (it's free to give kudos!) or share it on socials, but we're not averse to offering you some benefits at our 🍻 Patreon 🍻 either, if you're so inclined!