Skip to content

NuGet#

The BSR exposes a NuGet v3 repository at https://buf.build/gen/nuget/index.json, so any tool that speaks NuGet (dotnet, Visual Studio, Rider) can install BSR-generated C# SDKs:

$ dotnet add package BSR.Connectrpc.Eliza.Grpc.Csharp

For an end-to-end walkthrough, see the generated SDKs quickstart.

Configure NuGet.config#

Add the BSR feed to a NuGet.config file. For repo-scoped use, place it next to your .sln; for machine-wide use, place it in the standard user location (~/.nuget/NuGet/NuGet.config on Linux/macOS, %APPDATA%\NuGet\NuGet.Config on Windows). NuGet merges multiple configuration files when both exist.

Create a BSR token (see Authentication: Create a token) and put it in the ClearTextPassword field below:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
        <add key="BSR" value="https://buf.build/gen/nuget/index.json" protocolVersion="3" />
    </packageSources>
    <packageSourceCredentials>
        <BSR>
            <add key="Username" value="{bsr-username}" />
            <add key="ClearTextPassword" value="{token}" />
            <add key="ValidAuthenticationTypes" value="Basic" />
        </BSR>
    </packageSourceCredentials>
    <packageSourceMapping>
        <packageSource key="nuget.org">
            <package pattern="*" />
        </packageSource>
        <packageSource key="BSR">
            <package pattern="BSR.*" />
        </packageSource>
    </packageSourceMapping>
</configuration>

{bsr-username} is the BSR account username that owns the token. The field has to be non-empty, but the BSR matches authentication on the token itself.

Two parts of this configuration aren’t optional:

  • ValidAuthenticationTypes=Basic: the BSR feed authenticates over HTTP Basic.
  • The BSR.* package-source mapping: generated package IDs always start with BSR., and this mapping keeps dotnet restore from falling back to nuget.org for those packages.

Install an SDK#

Reference the SDK by its package ID:

$ dotnet add package BSR.Connectrpc.Eliza.Grpc.Csharp

The example installs the connectrpc/eliza module’s code generated by the grpc/csharp plugin. Every BSR-generated NuGet package follows the naming rule below.

Package names#

Each generated SDK is named:

BSR.{Module-Owner}.{Module-Name}.{Plugin-Owner}.{Plugin-Name}

Each segment is title-cased to follow C# package-naming conventions. For example, BSR.Connectrpc.Eliza.Grpc.Csharp is the connectrpc/eliza module produced by the grpc/csharp plugin.

For the exact name and version of a specific SDK, open the module’s SDKs tab on the BSR.

Versions#

Commits on a module’s default label produce released versions; every other commit produces an unreleased (NuGet prerelease) version. The two formats encode the plugin and module commit a little differently to fit NuGet’s version rules.

Released versions#

{pluginMajor}.{pluginMinor}.1{pluginPatch}{pluginRevision}.{sequenceNumber}+{commitShortName}

# Example
27.2.10001.12+6bcea16e2570

The pluginPatch and pluginRevision segments are each zero-padded to two digits and concatenated after a fixed leading 1, which sidesteps a NuGet limitation around minor-only version components. For the example 10001:

  • 1: fixed leading digit.
  • 00: pluginPatch (zero-padded), so plugin patch is 0.
  • 01: pluginRevision (zero-padded), so plugin revision is 1.

The version above represents:

  • Plugin major: 27
  • Plugin minor: 2
  • Plugin patch: 0
  • Plugin revision: 1
  • Sequence number: 12
  • Commit short name: 6bcea16e2570

Unreleased versions#

{pluginMajor}.{pluginMinor}.1{pluginPatch}{pluginRevision}.0-{commitTimestamp}-{commitShortName}

# Example
27.2.10001.0-20240717164601-6bcea16e2570

Same 1{pluginPatch}{pluginRevision} encoding as the released form. The trailing -{commitTimestamp}-{commitShortName} makes the version a NuGet prerelease, so released versions sort above it.

The example represents:

  • Plugin major: 27
  • Plugin minor: 2
  • Plugin patch: 0
  • Plugin revision: 1
  • Commit timestamp: 20240717164601
  • Commit short name: 6bcea16e2570

The BSR supports commits on labels: pushing to a non-default label lets consumers resolve work-in-progress changes through the unreleased-version channel without disturbing the default label.

Available plugins#

The full list of supported C# plugins lives on the BSR plugins page (filter for C#). For how those plugins are packaged, see the bufbuild/plugins repository; to request a new plugin, file an issue.