Discussed in #34
Originally posted by viceroypenguin January 23, 2021
Proposal: Add another project for exposing string and Stream versions of embedded resources. Accessing the resources is something necessary for most source generators, but also for many other projects; you're accessing embedded resources already in the other ThisAssembly.* projects. It would be nice to be able to have compile-time named access to the embedded resources. Thoughts?
Design
Given the following items in a project:
<PropertyGroup>
<EmbeddedResourceStringExtensions>$(EmbeddedResourceStringExtensions);.sql</EmbeddedResourceStringExtensions>
</PropertyGroup>
<ItemGroup>
<EmbeddedResource Include="Foo.txt" />
<EmbeddedResource Include="MyTemplate.template" Type="Text" />
<EmbeddedResource Include="Data\Bar.json" />
<EmbeddedResource Include="..\..\Branding\Icon.png" Link="Branding\Icon.png" Comment="Main app logo" />
<EmbeddedResource Include="Resources.resx" />
</ItemGroup>The generator would emit a class like the following:
partial class ThisAssembly
{
public static partial class Resources
{
// <summary>Resources\Foo.txt</summary>
public static partial class Foo
{
public static string Text => // return cached string version of the resource
public static byte[] GetBytes() => // read bytes from resource
public static Stream GetStream() => // get the resource stream
}
// <summary>MyTemplate.template</summary>
public static partial class MyTemplate
{
public static string Text => // return cached string version of the resource
public static byte[] GetBytes() => // read bytes from resource
public static Stream GetStream() => // get the resource stream
}
// <summary>Resources.resx</summary>
public static partial class Resources
{
public static byte[] GetBytes() => // read bytes from resource
public static Stream GetStream() => // get the resource stream
}
public partial class Branding
{
// <summary>Main app logo</summary>
// <remarks>Branding\Icon.png</remarks>
public static partial class Icon
{
public static byte[] GetBytes() => // read bytes from resource
public static Stream GetStream() => // get the resource stream
}
}
public partial class Data
{
// <summary>Data\Bar.json</summary>
public static partial class Bar
{
public static string Text => // return cached string version of the resource
public static byte[] GetBytes() => // read bytes from resource
public static Stream GetStream() => // get the resource stream
}
}
}
}From the example, note:
- All
EmbeddedResource items get a static class with both GetBytes and GetStream methods for retrieval
- Text files (i.e.
.txt and .json) also get a Text property with a cached string read from the resource
- Only certain file extensions within
EmbeddedResources items are defaulted to Text type (therefore getting a generated Text property). By default, this includes .txt;.json, but can be be extended by appending more extensions to the EmbeddedResourceStringExtensions property.
- A single
EmbeddedResource can also be annotated with the Type="Text" attribute too, to get the Text property just for that item.
- The items' target path (that is,
%(RelativeDir)\%(Filename)%(Extension) or %(Link) (for linked files) is used by default as the class <summary /> documentation, unless a Comment="...." is provided in the item, in which case that becomes the <summary /> and the former becomes the <remarks>.
- The relative directory of the item is used in the class structure to nest classes and avoid name collisions (this is prevented by the solution structure itself too at that point). This is similar to the nesting done by ThisAssembly.Constants
Discussed in #34
Originally posted by viceroypenguin January 23, 2021
Proposal: Add another project for exposing
stringandStreamversions of embedded resources. Accessing the resources is something necessary for most source generators, but also for many other projects; you're accessing embedded resources already in the other ThisAssembly.* projects. It would be nice to be able to have compile-time named access to the embedded resources. Thoughts?Design
Given the following items in a project:
The generator would emit a class like the following:
From the example, note:
EmbeddedResourceitems get a static class with bothGetBytesandGetStreammethods for retrieval.txtand.json) also get aTextproperty with a cached string read from the resourceEmbeddedResourcesitems are defaulted toTexttype (therefore getting a generatedTextproperty). By default, this includes.txt;.json, but can be be extended by appending more extensions to theEmbeddedResourceStringExtensionsproperty.EmbeddedResourcecan also be annotated with theType="Text"attribute too, to get theTextproperty just for that item.%(RelativeDir)\%(Filename)%(Extension)or%(Link)(for linked files) is used by default as the class<summary />documentation, unless aComment="...."is provided in the item, in which case that becomes the<summary />and the former becomes the<remarks>.