Skip to content

Simplify .NET Framework packaging: target frameworks, SDK-style projects and bundled dependencies in Core, Device and Server #1374

Closed

Description

@sacOO7

Summary

Ably.PubSub.Device and Ably.PubSub.Server both support .NET Framework 4.6.2+, .NET 6+ (including
MAUI) and other netstandard2.0 platforms. #1373
fixed Ably.PubSub.Device on .NET Framework. It also added a test that installs the packed packages
into .NET Framework and .NET 6/7 apps and runs them.

Two things make the packaging more complex than it needs to be:

  • Ably.PubSub.Device ships different builds from Ably.PubSub.Core and Ably.PubSub.Server;
  • the net46 builds of Core and Server come from separate old-style projects.

This issue proposes shipping the same target frameworks in all three packages, built from SDK-style
projects only. It's an optional clean-up for a later 2.x release, and isn't needed for 2.0.

Current layout

Package Builds shipped Build used by a .NET Framework app
Ably.PubSub.Core net46, netstandard2.0, net6.0, net7.0 net46
Ably.PubSub.Server net46, netstandard2.0, net6.0, net7.0 net46
Ably.PubSub.Device netstandard2.0, net6.0, net7.0 netstandard2.0

The net46 builds come from src/Ably.PubSub.Core.NETFramework and
src/Ably.PubSub.Server.NETFramework. These are old-style projects (packages.config, v4.6.2)
that need Windows or Mono msbuild to build. Everything else is SDK-style.

The net46 Core also has its own AssemblyInfo.cs, separate from the SDK-style Core's, and the
two have to be kept in step. The doors depend on Core's InternalsVisibleTo grants, and drift
between those two files is what PR 1373 fixed for Device.

Proposal

Ship the same targets in all three packages, from SDK-style projects only, and remove the two
.NETFramework projects. The target set is one of:

Either way:

  • Drop net7.0. It has no code of its own, and net6.0 covers .NET 7 and later.
  • Keep the agent header correct. Report .NET Framework from src/Ably.PubSub.Core/Platform.cs.
    Today only the net46 build reports it, because its Platform.cs hard-codes Framework.
  • Update the test. Change the expected builds in cake-build/tasks/package-consumption.cake.

Core has very little target-specific code. Apart from Platform.cs, the only difference is the OS
detection in src/Ably.PubSub.Shared/Agent.cs (#if NET5_0_OR_GREATER), which the net6.0 build
keeps.

Trade-offs

  • Pros:
    • the door and Core always come from the same build;
    • one project per package;
    • the NuGet packages no longer need Windows or Mono to pack, once package.cake moves from Mono
      msbuild and nuget.exe to the .NET SDK.
  • Cons:
    • with option A, apps on .NET Framework 4.6.2–4.7.1 get the netstandard2.0 build, which has
      known issues before 4.7.2;
    • with option B, there's a third target to build and test, and its tests still need Windows or
      Mono.
  • Work: these all need updating:
    • the nuspecs;
    • Ably.PubSub.NetFramework.sln, Ably.PubSub.Package.sln and Ably.PubSub.sln;
    • package.cake and the Cake build and test targets;
    • the .NET Framework test project (its Core reference and Core's InternalsVisibleTo);
    • CI;
    • README requirements, CONTRIBUTING.md, cake-build/README.md and the CHANGELOG;
    • the Unity plugin.

Done when

  • All three nuspecs ship the same target frameworks, built from SDK-style projects.
  • .NET Framework apps still report Framework in the agent header.
  • Test.PackageConsumption runs in CI and passes on .NET Framework (Windows and Mono) and on .NET.
  • The Unity plugin is regenerated, and the docs and CHANGELOG are updated.

Open questions

  1. Option A or B?
  2. net6.0 or net8.0 as the modern target? With net8.0, .NET 6/7 apps would fall back to
    netstandard2.0 and lose the OperatingSystem.* OS detection.
  3. With option A, keep 4.6.2 as the documented .NET Framework minimum, or move to 4.7.2?

┆Issue is synchronized with this Jira Story by Unito

Activity

  1. changed the title [-]Ship the same target frameworks in Ably.PubSub.Core, Device and Server[/-] [+]Simplify .NET Framework packaging: target frameworks, SDK-style projects and bundled dependencies in Core, Device and Server[/+] on Nov 2, 2026
  2. sacOO7 commented on Nov 2, 2026

    @sacOO7
    ContributorAuthor

    Decision for 2.0.0: Newtonsoft.Json and DeltaCodec on .NET Framework

    Summary

    In 2.0.0, Newtonsoft.Json (13.0.1 or later) is a normal NuGet dependency on every target, including .NET Framework, instead of being merged into the SDK as in 1.x. IO.Ably.DeltaCodec will be merged into the net46 build of Ably.PubSub.Core, as 1.2.16–1.2.19 did. Two other PRs stop the app's JsonConvert.DefaultSettings leaking into the SDK's wire format on all targets (issue 1143), and remove Server's net46 build.

    Why 1.x bundled Newtonsoft

    • Possible NewtonSoft incompatibility #91 (2017): a customer's supplier tool couldn't work with the Json.NET 9.x that ably.io required. A build that merged every dependency except MsgPack into IO.Ably.dll solved it.
    • Signed assembly #103 (2017): a signed customer app failed with "A strongly-named assembly is required" (0x80131044), first on the unsigned IO.Ably, then on its unsigned dependency Nito.AsyncEx. A signed, merged build (bed68b35) solved it.
    • Allow to send raw jtoken/jobject instead object #321 (2019), the maintainer's summary: "We currently bundle json.net with the ably binary in .net and xamarin to stop people having issues if they are using older version of the json.net."

    From 2017 until 2.0, the merge (ILRepack with internalized types; re-enabled with signing in b1e667f2) only ever covered the .NET Framework and Xamarin NuGet builds. The netstandard and .NET 6+ builds always took Newtonsoft as a NuGet dependency.

    What bundling cost users

    • On .NET Framework, the app's own JObject and JToken couldn't be used with the SDK, because its public signatures named the internal copy. Compiling against the 1.2.19 net46 IO.Ably.dll gives CS0029 for DeviceDetails.Metadata, CS1503 for AblyRest.Request(...)'s JToken body and Push.Admin.PublishAsync(JObject, JObject), and CS0122 for HttpPaginatedResponse.Items. The same code compiles on .NET.
    • Users couldn't update the hidden copy. Up to 1.2.16 it was Newtonsoft 9.0.1, which is affected by CVE-2024-21907 / GHSA-5crp-9r3c-p9vr.

    Why 2.0 uses a normal dependency

    • JObject and JToken interop works on every target.
    • Users get Newtonsoft fixes by updating the package.
    • With Stop the app's global JSON settings from changing the SDK's wire format #1382, the SDK's JSON no longer depends on the app's JsonConvert.DefaultSettings on any target. In 1.x, only the merged .NET Framework and Xamarin builds had that.
    • It fits this issue's alignment goal: under option A, .NET Framework apps would use the netstandard2.0 build, which never merged Newtonsoft.

    The change started as a side effect of removing the Xamarin heads, and the merge step with them, in #1333. Its description called it "the main thing I would want confirmed before GA". This comment records that it's confirmed.

    What it means for .NET Framework apps

    • Apps already on Newtonsoft 13.x have nothing to do. Every 13.x has AssemblyVersion 13.0.0.0.
    • An app that pins a version below 13 gets NU1605 at restore, and needs to upgrade.
    • An app that uses a library built against an older Newtonsoft needs a binding redirect. Exe projects generate one automatically, and Visual Studio prompts web projects to add one. Plug-ins in hosts that own the config file (for example Revit/AutoCAD, SSIS or Windows PowerShell 5.1 modules) usually can't, and can get FileLoadException if the host, another plug-in or one of their own libraries uses a Newtonsoft older than 13.
    • Merge DeltaCodec into the .NET Framework build of Ably.PubSub.Core and document Newtonsoft.Json on .NET Framework #1383 adds an UPDATING.md section, "Newtonsoft.Json on .NET Framework", covering these cases.

    DeltaCodec

    • The net46 Ably.PubSub.Core.dll is signed and references the unsigned IO.Ably.DeltaCodec.dll. Microsoft's strong-naming guidance says "a strong-named assembly can only reference other strong-named assemblies". Issue 103 is a precedent: the signed IO.Ably 0.8.4.5 couldn't load its unsigned Nito.AsyncEx for two users, though not in the maintainer's sample app.
    • Merging DeltaCodec into the net46 Core leaves one signed file. Only net46 changes; the other builds keep a separate IO.Ably.DeltaCodec.dll.
    • A correction to item 2 of 2.0 NuGet release readiness: new Ably.PubSub.* packages, ably.io deprecation, and pre-GA blockers #1356, which says 1.x never shipped this combination on net46. 1.2.1–1.2.15 did: a signed IO.Ably.dll next to an unsigned IO.Ably.DeltaCodec.dll. We haven't found any reported failures, but the risk isn't ruled out, since only delta=vcdiff channels load DeltaCodec.

    Server's net46 build

    #1381 removes src/Ably.PubSub.Server.NETFramework for 2.0.0. It compiles the same PubSubServer.cs and Side.cs with no .NET Framework-specific code, and was added in b5cbf6ad (#1334) only to mirror the Core's. .NET Framework apps will use Server's netstandard2.0 build with the net46 Core, as they do for Device. Once it's merged, the description's Server row and its mentions of src/Ably.PubSub.Server.NETFramework will be out of date.

    What stays in this issue

    • The target-framework alignment, the removal of src/Ably.PubSub.Core.NETFramework, and the open questions above.
    • Whichever option is chosen, the Core build that .NET Framework apps load must have DeltaCodec merged into it, or DeltaCodec must be signed. Under option A that's the netstandard2.0 build, which is also signed.

    Related

  3. sacOO7 commented on Nov 2, 2026

    @sacOO7
    ContributorAuthor

    We are doing DeltaCodex.DLL packaging using ILRepack for Ably.PubSub.Core for net46 so this issues is irrelevant now.
    Since, we will always need net46 for Ably.PubSub.Core and we can't ignore it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or improved functionality.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions