What go2cs promises to C# code that uses it

A C# project that references a go.* or nugetgo.* package, or calls code go2cs converted, binds to names that go2cs chose. This page says which of those names are a promise and which are not, and how a promised name may change.

There are three tiers. Every consumer-visible name is in one of them, or is a contract member of a type, which goes with that type.

Tier 1: frozen

These do not change. A change to any of them is a break, and takes the deprecation path.

Tier 2: stable within a Go minor release

These are what converted code itself uses. They do not change between revisions of one Go minor release (1.26.x). They may change when the break floor moves, and only then. C# code should not name them, and IntelliSense hides them: each carries [EditorBrowsable(EditorBrowsableState.Never)].

A type in a generated host is plumbing, but its methods are not. The promoted methods a host carries are part of the Go method set, so they stay visible in member completion; only the host’s own name is hidden.

Contract members

go2cs-gen also writes public members onto the Go types themselves. Those a C# caller binds to are contract members: they stay visible and go with the tier of the type they belong to. They are:

Any other generated public member is hidden. The list is checked: GenTests’ HiddenPlumbingTests fails on a generated public member that is neither hidden nor one of these.

Tier 3: no promise

These can change in any release. At this release no package marks them and no build warning names a use of them.

Diagnostic codes

MSBuild properties

For a project that references go.* or nugetgo.* packages:

Property Default What it does
GoConsumerUsings on The global using go; and using static go.builtin;, and each directly referenced package’s namespace. false turns them off.
GoGlobalPackageAliases off Also a global alias per referenced package, named for the Go package (hex for go.encoding.hex_package).
GoAllowBelowBreakFloor off Builds against a package below the break floor, with a warning instead of GO2CS3002.
GoBreakFloor the release’s floor The break floor itself. A Directory.Build.targets can lower it; the project file cannot.
GoCompileRuntimeIdentifier the build’s RID, else the host’s The platform whose build of a platform-split package the project compiles against.
GoRidCompileAssets on Compiles against that platform’s build. false compiles against lib/ (Windows).
GoAllowReferenceFlavor off As a global property only (-p:): runs the Windows build on a platform the packages do not ship, instead of GO2CS3003/GO2CS3004.
GoCopyPackageSymbols on Copies the packages’ .pdb files to the output, so a Go traceback prints file and line.
GoKeepSymbolsLoose on Keeps those .pdb files beside a single-file publish.

For a converted project that builds against a local standard library: GoTargetOS (windows, linux or darwin) picks the platform build of each package.

Other properties go.lib sets are internal and can change.

How a promised name changes

A tier-1 or tier-2 name changes in one of two ways, and no other:

  1. When the old name can coexist with its replacement, the old one stays for one release, marked [Obsolete] with the replacement named, and is removed in the next.
  2. When it cannot, the change ships as a set:
    • the break floor moves to the release that makes it, so a package built against the old surface stops the build by name instead of failing at run time;
    • the package’s compatibility check records the change;
    • the release notes have an “Upgrading” section that says what changed and what to do;
    • every published nugetgo.* package is rebuilt against the new release.

Before each release, the previous release’s C# consumer program (src/tests/CSharpConsumer) is built unchanged against the new packages and must pass all its checks (release-smoke, arm H). That build fails when a name the program uses is changed any other way; a name it does not use is not tested there. golib’s own tier-1 types and members are held line by line by its baseline, src/core/golib/PublicSurface.golib.txt, whose test fails on any change to them.

A release that breaks by design, the second way above, makes that build red on purpose. Its release smoke then builds an updated consumer, named with the consumer_ref input, and must cite the break with consumer_override: floor=<the moved break floor>;news=<the release notes>. The arm refuses the override unless the floor is the one the tree declares and lies above the previous release, and the release notes hold an “Upgrading from " entry. Its verdict line then reads OVERRIDE, so the exception is visible in the release's record.

Go interfaces you implement in C#

A C# class can implement a converted Go interface, as io.Writer does in the consumer guide. go2cs never adds an abstract member to a Go-named interface. Anything it adds is either implemented on the interface itself or lives on a separate interface, so a class written against one release keeps compiling against the next.