ThisAssembly_Resources by Daniel Cazzulino
Nuget / site data
Details
Info
Name: ThisAssembly_Resources
C# 9.0+ ONLY
This package generates a static ThisAssembly.Resources class with public
properties exposing string and Stream shortcuts to access embedded resources.
Author: Daniel Cazzulino
NuGet: https://www.nuget.org/packages/ThisAssembly.Resources/
You can find more details at https://www.clarius.org/ThisAssembly/
Original Readme
============
Exposes project and assembly level information as constants in the ThisAssembly class using source generators powered by Roslyn.
The main generated entry point type is ThisAssembly in the global namespace,
and is declared as partial so you can extend it too with manually created members.
Each package in turn extends this partial class to add their own nestes types and members.
The ThisAssembly meta-package includes all the other packages for convenience.
NOTE: for now, ThisAssembly only generates C# code.
ThisAssembly.AssemblyInfo
This package generates a static ThisAssembly.Info class with public
constants exposing the following attribute values generated by default for SDK style projects:
AssemblyConfigurationAttribute
AssemblyCompanyAttribute
AssemblyTitleAttribute
AssemblyDescriptionAttribute
AssemblyProductAttribute
AssemblyCopyrightAttribute
AssemblyVersionAttribute
AssemblyInformationalVersionAttribute
AssemblyFileVersionAttribute
If your project includes these attributes by other means, they will still be emitted properly
on the ThisAssembly.Info class.
ThisAssembly.Constants
This package generates a static ThisAssembly.Constants class with public
constants for @(Constant) MSBuild items in the project.
<ItemGroup>
<Constant Include="Foo.Bar" Value="Baz" Comment="Yay!" />
<Constant Include="Foo.Hello" Value="World" Comment="Comments make everything better 😍" />
</ItemGroup>
In addition to arbitrary constants via <Constant ...>, it's quite useful (in particular in test projects)
to generate constants for files in the project, so there's also a shorthand for those:
<ItemGroup>
<FileConstant Include="@(Content)" />
</ItemGroup>
Which results in:
ThisAssembly.Git
This package generates a static ThisAssembly.Git class with constants
for the following Git properties from the current project:
- Commit
- Sha (first 9 chars from Commit)
- Root (normalized to forward slashes)
- Url (if PublishRepositoryUrl=true)
- Branch (from CI environment variables)
This package relies on your project's installed Microsoft.SourceLink.* package reference according to your specific Git-based source control server (such as GitHub, Azure DevOps, BitBucket, etc).
The Branch property is populated from environment variables provided
by the currently supported CI systems: GitHub Actions, Azure DevOps,
AppVeyor, TeamCity, Travis CI, Circle CI, GitLab CI, Buddy, and Jenkins.
Whenever the CI system provides a pull request number, the branch name is
pr[NUMBER], such as pr123. This makes it easy to use it as a semver
metadata label.
Note: by default, the values of these constants are populated during "real" builds (that is, not IDE/design-time builds used to populate intellisense). This is to avoid negatively affecting the editor's performance. This means, however, that the properties will seem to always be empty when inspecting them in the IDE (although never at run-time). If you want to force population of these values for design-time builds, set the
EnableSourceControlManagerQueriesproperty totrue. This property is defined and documented by dotnet/sourcelink.
At the MSBuild level, targets can take a dependency on the provided
InitializeGitInformation target, which sets the equivalent properties
named:
- RepositoryCommit
- RepositorySha
- RepositoryRoot
- RepositoryUrl
- RepositoryBranch
The names of these properties were chosen on purpose to match the properties used by nuget pack and nugetizer to populate the relevant package metadata.
So if you have a GitHub repository, installing these three packages will ensure you have the proper metadata out of the box and the simplest packaging experience possible:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.SourceLink.GitHub" />
<PackageReference Include="ThisAssembly.Git" />
<PackageReference Include="NuGetizer" />
</ItemGroup>
</Project>
ThisAssembly.Metadata
This package provides a static ThisAssembly.Metadata class with public
constants exposing each [System.Reflection.AssemblyMetadata(..)] defined for
the project.
For an attribute declared (i.e. in AssemblyInfo.cs) like:
[assembly: System.Reflection.AssemblyMetadataAttribute("Foo", "Bar")]
A corresponding ThisAssembly.Metadata.Foo constant with the value Bar is provided.
The metadata attribute can alternatively be declared using MSBuild syntax in the project
(for .NET 5.0+ projects that have built-in support for @(AssemblyMetadata) items):
<ItemGroup>
<AssemblyMetadata Include="Foo" Value="Bar" />
</ItemGroup>
ThisAssembly.Project
This package generates a static ThisAssembly.Project class with public
constants exposing project properties that have been opted into this mechanism by adding
them as ProjectProperty MSBuild items in the project file, such as:
<PropertyGroup>
<!-- Some arbitrary MSBuild property declared somewhere -->
<Foo>Bar</Foo>
</PropertyGroup>
<ItemGroup>
<!-- Opt-in to emitting that property value as a constant in ThisAssembly.Project -->
<ProjectProperty Include="Foo" />
</ItemGroup>
ThisAssembly.Resources
This package generates a static ThisAssembly.Resources class with public
properties exposing shortcuts to retrieve the contents of embedded resources.
This package generates a static ThisAssembly.Resources class with public
properties exposing typed APIs to retrieve the contents of embedded resources.
<ItemGroup>
<EmbeddedResource Include="Content/Docs/License.md" />
</ItemGroup>
Since markdown files are text files, the API will expose a Text property property
for it that will read its content once and cache it:
The $(EmbeddedResourceStringExtensions) MSBuild property allows customizing which
file extensions get treated as text files. By default, it's defined as:
<PropertyGroup>
<EmbeddedResourceStringExtensions>.txt|.cs|.sql|.json|.md</EmbeddedResourceStringExtensions>
</PropertyGroup>
You can append additional file extensions to this list, or override it completely. The list must be pipe-separated.
You can always use the provided GetStream and GetBytes for more advanced scenarios (or for
non-text resources).
Optionally, you can specify the Kind metadata for a specific EmbeddedResource you want
treated as a text file:
<EmbeddedResource Include="query.kql" Kind="Text" />
You can also add a Comment item metadata attribute, which will be used as the <summary> XML
doc for the generated member.
ThisAssembly.Strings
This package generates a static ThisAssembly.Strings class with public
constants exposing string resources in .resx files or methods with the right number of
parameters for strings that use formatting parameters.
In addition, it groups constants and methods in nested classes according to an optional underscore separator to organize strings. For example, User_InvalidCredentials can be accessed with ThisAssembly.Strings.User.InvalidCredentials if it contains a simple string, or as a method with the right number of parametres if its value has a format string.
Given the following Resx file:
| Name | Value | Comment |
|---|---|---|
| Infrastructure_MissingService | Service {0} is required. | For logging only! |
| Shopping_NoShipping | We cannot ship {0} to {1}. | |
| Shopping_OutOfStock | Product is out of stock at this time. |
The following code would be generated:
partial class ThisAssembly
{
public static partial class Strings
{
public static partial class Infrastructure
{
/// <summary>
/// For logging only!
/// => "Service {0} is required."
/// </summary>
public static string MissingService(object arg0)
=> string.Format(CultureInfo.CurrentCulture,
Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("MissingService"),
arg0);
}
public static partial class Shopping
{
/// <summary>
/// => "We cannot ship {0} to {1}."
/// </summary>
public static string NoShipping(object arg0, object arg1)
=> string.Format(CultureInfo.CurrentCulture,
Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("NoShipping"),
arg0, arg1);
/// <summary>
/// => "Product is out of stock at this time."
/// </summary>
public static string OutOfStock
=> Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("OutOfStock");
}
}
}
Dogfooding
We also produce CI packages from branches and pull requests so you can dogfood builds as quickly as they are produced.
The CI feed is https://pkg.kzu.io/index.json.
The versioning scheme for packages is:
- PR builds: 42.42.42-pr
[NUMBER] - Branch builds: 42.42.42-
[BRANCH].[COMMITS]
Sponsors
About
Embed resources to file
How to use
Example ( source csproj, source files )
- CSharp Project
- Program.cs
- mytext.sql
This is the CSharp Project that references ThisAssembly_Resources
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net7.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<EmbeddedResource Include="Content/mytext.sql" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="ThisAssembly.Resources" Version="1.4.1">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
</ItemGroup>
<PropertyGroup>
<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
<CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GX</CompilerGeneratedFilesOutputPath>
</PropertyGroup>
</Project>
This is the use of ThisAssembly_Resources in Program.cs
Console.WriteLine(ThisAssembly.Resources.Content.mytext.Text);
This is the use of ThisAssembly_Resources in mytext.sql
This is from file
Generated Files
Those are taken from $(BaseIntermediateOutputPath)\GX
- Content.mytext.g.cs
- ThisAssembly.Resources.EmbeddedResource.cs
//------------------------------------------------------------------------------
// <auto-generated>
// This code was generated by a tool.
//
// ThisAssembly.Resources: 1.4.1
//
// Changes to this file may cause incorrect behavior and will be lost if
// the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------
using System;
using System.IO;
partial class ThisAssembly
{
public static partial class Resources
{
public static partial class Content
{
/// <summary>
/// => @"Content\mytext.sql"
/// </summary>
public static partial class mytext
{
private static string text;
public static string Text => text ??= EmbeddedResource.GetContent(@"Content\mytext.sql");
public static byte[] GetBytes() => EmbeddedResource.GetBytes(@"Content\mytext.sql");
public static Stream GetStream() => EmbeddedResource.GetStream(@"Content\mytext.sql");
}
}
}
}
using System;
using System.IO;
using System.Linq;
using System.Reflection;
static class EmbeddedResource
{
static readonly string baseDir = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location) ?? "";
public static string GetContent(string relativePath)
{
using var stream = GetStream(relativePath);
using var reader = new StreamReader(stream);
return reader.ReadToEnd();
}
public static byte[] GetBytes(string relativePath)
{
using var stream = GetStream(relativePath);
var bytes = new byte[stream.Length];
stream.Read(bytes, 0, bytes.Length);
return bytes;
}
public static Stream GetStream(string relativePath)
{
var filePath = Path.Combine(baseDir, Path.GetFileName(relativePath));
if (File.Exists(filePath))
return File.OpenRead(filePath);
var baseName = Assembly.GetExecutingAssembly().GetName().Name;
var resourceName = relativePath
.TrimStart('.')
.Replace('/', '.')
.Replace('\\', '.');
var manifestResourceName = Assembly.GetExecutingAssembly()
.GetManifestResourceNames().FirstOrDefault(x => x.EndsWith(resourceName));
if (string.IsNullOrEmpty(manifestResourceName))
throw new InvalidOperationException($"Did not find required resource ending in '{resourceName}' in assembly '{baseName}'.");
return
Assembly.GetExecutingAssembly().GetManifestResourceStream(manifestResourceName) ??
throw new InvalidOperationException($"Did not find required resource '{manifestResourceName}' in assembly '{baseName}'.");
}
}
Usefull
Download Example (.NET C# )
Share ThisAssembly_Resources
https://ignatandrei.github.io/RSCG_Examples/v2/docs/ThisAssembly_Resources