Repository navigation
Description
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.Deviceships different builds fromAbly.PubSub.CoreandAbly.PubSub.Server;- the
net46builds 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:
- A.
netstandard2.0+net6.0. .NET Framework apps use thenetstandard2.0build. - B.
net462+netstandard2.0+net6.0. This keeps a real .NET Framework binary, which
Microsoft suggests for apps on .NET Framework 4.6.2–4.7.1
(https://learn.microsoft.com/dotnet/standard/library-guidance/cross-platform-targeting).
SDK-style projects can buildnet462on any OS with the
Microsoft.NETFramework.ReferenceAssembliespackage.
Either way:
- Drop
net7.0. It has no code of its own, andnet6.0covers .NET 7 and later. - Keep the agent header correct. Report .NET Framework from
src/Ably.PubSub.Core/Platform.cs.
Today only thenet46build reports it, because itsPlatform.cshard-codesFramework. - 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.cakemoves from Mono
msbuildandnuget.exeto the .NET SDK.
- Cons:
- with option A, apps on .NET Framework 4.6.2–4.7.1 get the
netstandard2.0build, 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.
- with option A, apps on .NET Framework 4.6.2–4.7.1 get the
- Work: these all need updating:
- the nuspecs;
Ably.PubSub.NetFramework.sln,Ably.PubSub.Package.slnandAbly.PubSub.sln;package.cakeand 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.mdand 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
Frameworkin the agent header. -
Test.PackageConsumptionruns 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
- Option A or B?
net6.0ornet8.0as the modern target? Withnet8.0, .NET 6/7 apps would fall back to
netstandard2.0and lose theOperatingSystem.*OS detection.- 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
[-]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[/+]sacOO7 commentedon Nov 2, 2026
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.DeltaCodecwill be merged into thenet46build ofAbly.PubSub.Core, as 1.2.16–1.2.19 did. Two other PRs stop the app'sJsonConvert.DefaultSettingsleaking into the SDK's wire format on all targets (issue 1143), and remove Server'snet46build.Why 1.x bundled Newtonsoft
ably.iorequired. A build that merged every dependency except MsgPack intoIO.Ably.dllsolved it.0x80131044), first on the unsignedIO.Ably, then on its unsigned dependencyNito.AsyncEx. A signed, merged build (bed68b35) solved it.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
JObjectandJTokencouldn't be used with the SDK, because its public signatures named the internal copy. Compiling against the 1.2.19net46IO.Ably.dllgives CS0029 forDeviceDetails.Metadata, CS1503 forAblyRest.Request(...)'sJTokenbody andPush.Admin.PublishAsync(JObject, JObject), and CS0122 forHttpPaginatedResponse.Items. The same code compiles on .NET.Why 2.0 uses a normal dependency
JObjectandJTokeninterop works on every target.JsonConvert.DefaultSettingson any target. In 1.x, only the merged .NET Framework and Xamarin builds had that.netstandard2.0build, 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
13.0.0.0.FileLoadExceptionif the host, another plug-in or one of their own libraries uses a Newtonsoft older than 13.DeltaCodec
net46Ably.PubSub.Core.dllis signed and references the unsignedIO.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 signedIO.Ably0.8.4.5 couldn't load its unsignedNito.AsyncExfor two users, though not in the maintainer's sample app.net46Core leaves one signed file. Onlynet46changes; the other builds keep a separateIO.Ably.DeltaCodec.dll.net46. 1.2.1–1.2.15 did: a signedIO.Ably.dllnext to an unsignedIO.Ably.DeltaCodec.dll. We haven't found any reported failures, but the risk isn't ruled out, since onlydelta=vcdiffchannels load DeltaCodec.Server's
net46build#1381 removes
src/Ably.PubSub.Server.NETFrameworkfor 2.0.0. It compiles the samePubSubServer.csandSide.cswith no .NET Framework-specific code, and was added inb5cbf6ad(#1334) only to mirror the Core's. .NET Framework apps will use Server'snetstandard2.0build with thenet46Core, as they do for Device. Once it's merged, the description's Server row and its mentions ofsrc/Ably.PubSub.Server.NETFrameworkwill be out of date.What stays in this issue
src/Ably.PubSub.Core.NETFramework, and the open questions above.netstandard2.0build, which is also signed.Related
net46Core.JsonConvert.DefaultSettings, for Address JSON serialisation #1143. Without it, un-merging would bring that leak to .NET Framework.net46build.Newtonsoft.Json.dllthat could clash with Unity's, as reported in Unity: Newtonsoft JSON library conflicts with version that Unity includes by default #753.sacOO7 commentedon Nov 2, 2026
We are doing
DeltaCodex.DLLpackaging usingILRepackforAbly.PubSub.Corefornet46so this issues is irrelevant now.Since, we will always need
net46forAbly.PubSub.Coreand we can't ignore it.