Pinecone.TypedPath
1.1.0
dotnet add package Pinecone.TypedPath --version 1.1.0
NuGet\Install-Package Pinecone.TypedPath -Version 1.1.0
<PackageReference Include="Pinecone.TypedPath" Version="1.1.0" />
<PackageVersion Include="Pinecone.TypedPath" Version="1.1.0" />
<PackageReference Include="Pinecone.TypedPath" />
paket add Pinecone.TypedPath --version 1.1.0
#r "nuget: Pinecone.TypedPath, 1.1.0"
#:package Pinecone.TypedPath@1.1.0
#addin nuget:?package=Pinecone.TypedPath&version=1.1.0
#tool nuget:?package=Pinecone.TypedPath&version=1.1.0
Typed Path
.NET source generator for strongly typed file paths.
Install
Install the package from nuget:
dotnet add package Pinecone.TypedPath
The package ships the generator under analyzers/dotnet/cs, so a plain package
reference is enough. PrivateAssets="all" keeps it out of your consumers' dependency
graph:
<ItemGroup>
<PackageReference Include="Pinecone.TypedPath" Version="..." PrivateAssets="all" />
</ItemGroup>
Requirements
- A compiler with incremental source generator support: Roslyn 4.8 or newer (.NET 8 SDK / Visual Studio 2022 17.8+).
- No target-framework restriction. The generated code is plain C# —
netstandard2.0, .NET Framework 4.6.2+ and .NET 6+ all work.
Configuration
The src/TypedPath.Sample project includes the full example.
First add the folder to the .csproj as AdditionalFiles:
<ItemGroup>
<AdditionalFiles Include="Assets/**" />
</ItemGroup>
Then define a partial class with the TypedPath attribute:
[TypedPath("Assets")]
public partial class Assets
{
}
Every file under Assets becomes a nested class member:
> Console.WriteLine(Assets.SubFolder.NestedFolder.SuperNested);
Assets/SubFolder/NestedFolder/SuperNested.json
Customising the value with ITypedPath
ITypedPath is an optional marker interface. Implement it — and a
public static string Wrap(string path) method — when the generated value needs to be
transformed at runtime (adding a CDN prefix, rewriting an extension, resolving against a
base directory, …):
[TypedPath("Assets")]
public partial class Assets : ITypedPath
{
public static string Wrap(string path)
{
return "https://cdn.example.com/" + path;
}
}
The generated members then call Wrap("Assets/logo.svg") instead of using the literal
directly. Wrap may also be inherited from a base class.
Constants versus runtime values
Without Wrap the generator emits const fields, so the paths can be used in
attribute arguments, case labels and any other constant context:
[AttributeUsage(AttributeTargets.Class)]
public sealed class AssetAttribute : Attribute
{
public AssetAttribute(string path) { }
}
[Asset(Assets.SubFolder.Logo)] // works because the member is a constant
public class MyThing { }
With Wrap the value is only known at runtime, so members are static readonly
instead. Adding a Wrap method later therefore turns the constants into fields and breaks
attribute/const usage — decide up front whether you need constant contexts.
Two things to keep in mind about constants: their values are inlined into every assembly
that uses them (changing a path means recompiling consumers), and reflection sees them as
IsLiteral/RawConstantValue rather than IsInitOnly. In practice this only matters when
the generated class is part of a published library.
Keeping the original file name
By default file names are PascalCased (some_json.json → SomeJson). Pass
originalFilename: true to keep the file-name stem exactly as written. Names that are
not valid C# identifiers are still sanitized:
[TypedPath("Assets", originalFilename: true)]
public partial class Assets : ITypedPath
{
public static string Wrap(string path) => path;
}
> Console.WriteLine(Assets.some_json);
Assets/some_json.json
Generated values
- The value always starts at the
[TypedPath]path, regardless of the class name:[TypedPath("Assets/SubFolder")] public partial class SubFolderproducesAssets/SubFolder/logo.svg. - Separators are always forward slashes (
/), including on Windows. - The casing MSBuild reports for the file is preserved.
- Values are proper C# literals: quotes and backslashes are escaped, and non-ASCII characters are preserved as UTF-8.
- Values are relative to the project directory.
AdditionalFilesoutside the project (for example../Shared/**) are ignored, because they cannot be expressed project-relative. This usesbuild_property.ProjectDir, which the package forwards; hosts that do not provide it fall back to heuristic matching, which can match unrelated files whose path contains the attribute segment.
Nested folders and identifiers
Folder names become nested partial classes and are PascalCased, exactly like file names:
Assets/subfolder/logo.svg → Assets.Subfolder.Logo. Segments that are not valid C#
identifiers are sanitized (my-docs → MyDocs, 2024 → _2024), and file names starting
with a digit get a _ prefix (1st.png → _1st). A TP006 informational diagnostic
reports sanitized names; ordinary casing changes are silent.
If two file names would generate the same member, the lexicographically first path keeps
the name and the others are suffixed: logo.svg + logo.png → Logo and Logo_2 (reported as TP004). The same
happens for names C# reserves: the enclosing class name, Wrap when it is used, object
members such as ToString, and any member already declared on the class or inherited from
a base class.
Folders whose names sanitize to the same identifier (my-docs and my_docs) are
merged into one generated class rather than suffixed.
Diagnostics
| ID | Severity | Meaning |
|---|---|---|
| TP001 | Error | The [TypedPath] class is not partial. |
| TP002 | Error | A Wrap method exists but cannot be used (it must be static, return string and take one string). |
| TP003 | Warning | The [TypedPath] path matched no AdditionalFiles. |
| TP004 | Warning | A generated member name was disambiguated because of a collision. |
| TP005 | Warning | [TypedPath] was used, but the project has no AdditionalFiles. |
| TP006 | Info | A folder or file name was rewritten into a valid C# identifier. |
| TP007 | Error | The class implements ITypedPath but provides no accessible static string Wrap(string). |
| TP008 | Error | The [TypedPath] class is generic, which is not supported. |
| TP009 | Error | The declaration is not supported (nested, file-local or not a class). |
TP004 is a warning even though the generator already fixed the output, because renaming
the source file is the better fix. Projects with TreatWarningsAsErrors may want to lower
it to suggestion.
Each diagnostic can be tuned per ID in .editorconfig, for example:
[*.cs]
dotnet_diagnostic.TP004.severity = none
Known limitations
- Each
[TypedPath]class must be a non-generic, top-level, non-file-local class. Records, nested classes, file-local classes and generic classes are reported asTP008/TP009rather than ignored; structs, interfaces and enums are rejected by the attribute itself (AttributeUsage(AttributeTargets.Class)). - If a library that uses TypedPath is referenced from a project that also uses TypedPath,
both assemblies generate
TypedPathAttribute/ITypedPathand the compiler reportsCS0436. The generated types are identical; suppress the warning with<NoWarn>$(NoWarn);CS0436</NoWarn>. [TypedPath]takes a folder path, not a path to an individual file.- Two files whose names differ only by extension, or a file and a folder with the same name, produce suffixed members (see TP004).
- Folders that sanitize to the same identifier are merged.
- Folder names are always PascalCased;
originalFilenameapplies to file names only, so there is no opt-out for folder casing.
Building and releasing
The solution is src/TypedPath.slnx.
./scripts/build.sh # dotnet build -c Release
./scripts/test.sh # dotnet test -c Release
./scripts/pack.sh # artifacts/Pinecone.TypedPath.<version>.nupkg
NUGET_API_KEY=... ./scripts/publish.sh # build + test + pack + push to nuget.org
The version is the <Version> element in src/Directory.Build.props. publish.sh refuses to
run with a dirty working tree and skips packages that already exist on the feed.
Building this repository requires the .NET 10 SDK (the sample targets net10.0). Consuming
the package only requires a compiler with Roslyn 4.8 (.NET 8 SDK / VS 2022 17.8+).
Note for Rider
Related to RIDER-75959
While the source generator works with most file types (.json, .png, etc.),
Rider's IntelliSense may not detect changes with .txt and potentially other files.
Builds will still work correctly (this is purely an IDE issue).
Learn more about Target Frameworks and .NET Standard.
This package has 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.