Cobalt

Cobalt (MS-FSSHTTP)

In the past (in Office Web Apps 2013), some HTTP actions required support for the MS-FSSHTTP protocol — also known as Cobalt. This is no longer true with Office Online Server 2016+.

However, if the WOPI client discovers (via the SupportsCobalt property) that the WOPI host supports Cobalt, it will use it because it is more efficient for co-authoring.

Why it's off by default

Cobalt support depends on Microsoft.CobaltCore.dll (and, for the modern build, Microsoft.Cobalt.Base.dll). These DLLs are part of Office Web Apps 2013 / Office Online Server / SharePoint, and their license does not allow public redistribution — so they are not part of this repository, and the public NuGet feed does not host a Microsoft.CobaltCore package.

Rather than failing the build when that private package is missing, the solution detects whether the feed is reachable and skips Cobalt automatically when it isn't. A fresh clone — or a fork PR building on CI without the credentials — builds the rest of the solution with no errors. WopiHost.Cobalt and WopiHost.Cobalt.Tests simply compile as empty no-ops, and CheckFileInfo reports SupportsCobalt = false.

The IncludeCobalt switch

The behaviour is controlled by the IncludeCobalt MSBuild property in the root Directory.Build.props. It is auto-detected (no configuration needed) but can be forced:

IncludeCobalt	Result
auto → on	When the private feed is reachable: either COBALT_PACKAGES_TOKEN is set (used by CI), or a user-level NuGet.Config declares the feed (a developer who ran dotnet nuget add source). WopiHost.Cobalt and its tests build normally.
auto → off	Otherwise. WopiHost.Cobalt + WopiHost.Cobalt.Tests build as no-ops; the rest of the solution is unaffected.
-p:IncludeCobalt=true	Force on (build fails if the package can't be restored — useful to confirm your feed setup).
-p:IncludeCobalt=false	Force off (e.g. to reproduce the fork/clone experience locally).

The user-config probe is cross-platform — it checks %APPDATA%\NuGet\NuGet.Config on Windows and ~/.nuget/NuGet/NuGet.Config / ~/.config/NuGet/NuGet.Config on Linux/macOS.

Because nuget.config maps the cobalt feed to the Microsoft.CobaltCore package only (via packageSourceMapping), when Cobalt is off the restore never queries the private feed at all — so no credentials are needed to build everything else.

Enabling Cobalt

1. Get the package. If your organization has a valid Microsoft license for SharePoint / OOS / OWA, build Microsoft.CobaltCore.<version>.nupkg yourself — see Craft your own Microsoft.CobaltCore NuGet package, then host it on a private feed.

   ⚠️ The resulting package must not be redistributed publicly. Anyone consuming it needs a valid Microsoft license for the SharePoint / OOS / OWA installation that originally produced the binaries.

2. Make the feed reachable. Point nuget.config at your feed, then either:

   • set COBALT_PACKAGES_TOKEN (the credential referenced by nuget.config) as an environment variable — this is what CI uses; or
   • add the feed to your user-level NuGet config, e.g. dotnet nuget add source <feed-url> --name cobalt --username <user> --password <token> --store-password-in-clear-text.

3. Build. IncludeCobalt auto-detects the feed and WopiHost.Cobalt builds. Confirm with dotnet build WOPI.slnx -p:IncludeCobalt=true to force the path and surface any restore problem.

Skipping Cobalt

Do nothing — Cobalt is off by default and the build proceeds without it. OOS 2016+ does not require MS-FSSHTTP; the WOPI host still serves everything else, and only the more efficient co-authoring path is unavailable. (There is no longer any need to manually unload WopiHost.Cobalt from the solution.)

See also

• Craft your own Microsoft.CobaltCore NuGet package — step-by-step build instructions.
• WopiHost.Cobalt README — what the package wires up at runtime.
• MS-FSSHTTP specification — the protocol itself.