PodNet.EmbeddedTexts
1.2.3
Prefix Reserved
dotnet add package PodNet.EmbeddedTexts --version 1.2.3
NuGet\Install-Package PodNet.EmbeddedTexts -Version 1.2.3
<PackageReference Include="PodNet.EmbeddedTexts" Version="1.2.3"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add PodNet.EmbeddedTexts --version 1.2.3
#r "nuget: PodNet.EmbeddedTexts, 1.2.3"
// Install PodNet.EmbeddedTexts as a Cake Addin #addin nuget:?package=PodNet.EmbeddedTexts&version=1.2.3 // Install PodNet.EmbeddedTexts as a Cake Tool #tool nuget:?package=PodNet.EmbeddedTexts&version=1.2.3
PodNet.EmbeddedTexts
A simple C# incremental code generator that allows for efficiently embedding text file content into your code.
Usage
- Add the
PodNet.EmbeddedTexts
NuGet package to your .NET project. - 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>
:
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<ItemGroup> <AdditionalFiles Include="Files/**" /> </ItemGroup>
Build action
property of the file(s) to "C# analyzer additional file". Once you do, Visual Studio will edit your.csproj
file accordingly. - 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 isMyProject
, and you have anAdditionalFiles
element in your project'sFiles/MyFile.txt
file with contentfile 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 ofItemGroup
elements. TheAdditionalFiles
element can be used by all modern source generators and are not specific toPodNet.EmbeddedTexts
. One quirk of MSBuild items is that they can beInclude
d individually or by globbing patterns, but the execution and parsing of these files is (mostly) sequential, so if you have any filesInclude
d by any patterns, you then have toUpdate
them instead ofInclude
-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>
Additional configuration
You can set more properties to configure the generator further. See the examples below.
<Project>
<ItemGroup>
<AdditionalFiles Include="Files/My File.txt"
PodNet_EmbedTextNamespace="OtherNamespace"
PodNet_EmbedTextClassName="MyFileTXT"
PodNet_EmbedTextIsConst="true"
PodNet_EmbedTextIdentifier="Text"
PodNet_EmbedTextCommentContentLines="20" />
</ItemGroup>
</Project>
The above results in OtherNamespace.MyFileTXT.Content
being the property that holds the file content, which will be a const
value instead of a property, and will render up to the first 20 lines of the file contents into the IntelliSense documentation comment (the entirety of the file contents will be available in the constant value, however).
<Project>
<ItemGroup>
<AdditionalFiles Include="Files/**" />
<AdditionalFiles Update="Files/Folder/**"
PodNet_EmbedTextIsStaticClass="true"
PodNet_EmbedTextDirectoryAsClass="true"
/>
</ItemGroup>
</Project>
Above, we include
all files in the Files
folder (matched by the "Files/"
globbing pattern), then refine all files in the Files/Folder/**
path by applying two additional configuration values, which result in the generated classes being static
, and the containing folder being the name of the generated class instead of the name of the file (as well as the property being the name of the file instead of being just 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 org's [Discussions] or the project's topic, at our website at podnet.hu, or find us anywhere from LinkedIn 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!
Sponsorship
If you're using our work or like what you see, consider supporting us. Every bit counts. 🙏 See here for more info.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.