Pinecone.TypedPath 1.1.0

dotnet add package Pinecone.TypedPath --version 1.1.0
                    
NuGet\Install-Package Pinecone.TypedPath -Version 1.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Pinecone.TypedPath" Version="1.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Pinecone.TypedPath" Version="1.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Pinecone.TypedPath" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Pinecone.TypedPath --version 1.1.0
                    
#r "nuget: Pinecone.TypedPath, 1.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Pinecone.TypedPath@1.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Pinecone.TypedPath&version=1.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Pinecone.TypedPath&version=1.1.0
                    
Install as a Cake Tool

Typed Path

Nuget License GitHub

.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 SubFolder produces Assets/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. AdditionalFiles outside the project (for example ../Shared/**) are ignored, because they cannot be expressed project-relative. This uses build_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 as TP008/TP009 rather 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/ITypedPath and the compiler reports CS0436. 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; originalFilename applies 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).

There are no supported framework assets in this package.

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.

Version Downloads Last Updated
1.1.0 92 11/3/2026
1.0.4 238 1/4/2026
1.0.3 215 12/22/2025
1.0.2 209 12/22/2025