ably · umair-ably · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
@@ -5,10 +5,9 @@
 #
 # To create a release:
 # 1. Go to Actions tab → Package ably workflow
-# 2. Click "Run workflow" and enter the version number (e.g., 1.2.3)
+# 2. Click "Run workflow" and enter the version number (e.g., 2.0.0)
 # 3. Download artifacts:
-#    - ably-package: Main NuGet packages (.nupkg)
-#    - ably-push-package: Push notification packages (.nupkg)
+#    - ably-package: NuGet packages (.nupkg)
 #    - ably-unity-package: Unity package (.unitypackage)
 # ============================================================================
 
@@ -40,45 +39,6 @@ jobs:
             6.0.428
             7.0.410
 
-      - name: Setup Android SDK
-        uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3.2.2
-
-      - name: Install Android SDK Platform 30
-        shell: pwsh
-        run: |
-          echo "y" | & "$env:ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager.bat" "platforms;android-30"
-          echo "y" | & "$env:ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager.bat" "build-tools;30.0.3"
-
-      - name: Install legacy Xamarin
-        shell: pwsh
-        run: |
-          # Install Xamarin.Android and Xamarin.iOS components via VS installer
-          Write-Host "Installing Xamarin workload for VS 2022..."
-          Write-Host "This may take several minutes..."
-
-          & "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vs_installer.exe" modify `
-            --installPath "C:\Program Files\Microsoft Visual Studio\2022\Enterprise" `
-            --add Microsoft.VisualStudio.Workload.XamarinBuildTools `
-            --add Component.Xamarin `
-            --wait
-
-          Write-Host "Xamarin installation completed"
-
-          # Verify installation
-          Write-Host "Verifying Xamarin.iOS targets..."
-          if (-not (Test-Path "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Xamarin\iOS\Xamarin.iOS.CSharp.targets")) {
-            Write-Error "Xamarin.iOS targets not found at expected path"
-            exit 1
-          }
-          Write-Host "Verified Xamarin.iOS installation"
-
-          Write-Host "Verifying Xamarin.Android targets..."
-          if (-not (Test-Path "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Xamarin\Android\Xamarin.Android.CSharp.targets")) {
-            Write-Error "Xamarin.Android targets not found at expected path"
-            exit 1
-          }
-          Write-Host "Verified Xamarin.Android installation"
-
       - name: Download cake tool
         run: dotnet tool restore
 
@@ -94,67 +54,6 @@ jobs:
           path: |
             ${{ github.workspace }}/*.nupkg
 
-  package-push:
-    runs-on: macos-14
-    env:
-      DOTNET_NOLOGO: true
-
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-        with:
-          submodules: 'recursive'
-          persist-credentials: false
-
-      - name: Setup Xcode
-        uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
-        with:
-          xcode-version: '14.3'
-
-      - name: Setup Android SDK
-        uses: android-actions/setup-android@9fc6c4e9069bf8d3d10b2204b1fb8f6ef7065407 # v3.2.2
-
-      - name: Install Android SDK Platform 30
-        run: |
-          yes | "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" "platforms;android-30"
-          yes | "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" "build-tools;30.0.3"
-
-      - name: Download dotnet framework
-        uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4.3.1
-        with:
-          dotnet-version: |
-            3.1.426
-            6.0.428
-            7.0.410
-
-      - name: Install legacy Xamarin
-        run: |
-          # macOS 13 runners should have Xamarin pre-installed
-          # Verify Xamarin.iOS and Xamarin.Android are available
-          ls -la "/Library/Frameworks/Mono.framework/External/xbuild/Xamarin/" || true
-          ls -la "/Library/Frameworks/Xamarin.iOS.framework/" || true
-
-          # If not found, install via brew
-          if [ ! -d "/Library/Frameworks/Xamarin.iOS.framework/" ]; then
-            echo "Installing Xamarin via brew..."
-            brew install --cask xamarin-ios || true
-            brew install --cask xamarin-android || true
-          fi
-
-      - name: Download cake tool
-        run: dotnet tool restore
-
-      - name: Package Push (iOS & Android)
-        env:
-          VERSION: ${{ github.event.inputs.version }}
-        run: ./package-push.sh "$VERSION"
-
-      - name: Archive push packages
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: ably-push-package
-          path: |
-            ${{ github.workspace }}/*.nupkg
-
   package-unity:
     runs-on: ubuntu-22.04
     steps:
@@ -187,7 +86,7 @@ jobs:
 
   merge-artifacts:
     runs-on: ubuntu-22.04
-    needs: [package-library, package-push, package-unity]
+    needs: [package-library, package-unity]
     steps:
       - name: Download all artifacts
         uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
@@ -206,14 +105,6 @@ jobs:
             echo "Warning: ably-package artifact not found"
           fi
 
-          # Copy all .nupkg files from ably-push-package
-          if [ -d "artifacts/ably-push-package" ]; then
-            find artifacts/ably-push-package -name "*.nupkg" -exec cp {} output-package/ \;
-            echo "Copied .nupkg files from ably-push-package"
-          else
-            echo "Warning: ably-push-package artifact not found"
-          fi
-
           # Copy .unitypackage file
           if [ -d "artifacts/ably-unity-package" ]; then
             find artifacts/ably-unity-package -name "*.unitypackage" -exec cp {} output-package/ \;

diff --git a/.gitignore b/.gitignore
@@ -42,6 +42,10 @@ bld/
 # NUNIT
 *.VisualState.xml
 TestResult.xml
+*.trx
+
+# Cake test output (paths.cake: TestResults = test-results/)
+test-results/
 
 # Chutzpah Test files
 _Chutzpah*

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -22,12 +22,12 @@ If you want to incorporate `ably-dotnet` into your project from source (perhaps
 2. Open the solution you want to reference ably-dotnet from
 3. In Solution Explorer right click the root node (it will be labelled Solution 'YourSolutionName')
 4. Select Add > Existing Project from the context menu
-5. Browse to the ably-dotnet repository and add ably-dotnet\src\IO.Ably.Shared\IO.Ably.Shared.shproj
-6. Browse to the ably-dotnet repository and add the project that corresponds to your target platform, so if you are targeting .NET Framework (AKA Classic .NET) you would add ably-dotnet\src\IO.Ably.NETFramework\IO.Ably.NETFramework.csproj, if you are targeting .NET Core 2 then chose ably-dotnet\src\IO.Ably.NetStandard20\IO.Ably.NetStandard20.csproj and so on.
+5. Browse to the ably-dotnet repository and add ably-dotnet\src\Ably.PubSub.Shared\Ably.PubSub.Shared.shproj
+6. Browse to the ably-dotnet repository and add the project that corresponds to your target platform, so if you are targeting .NET Framework (AKA Classic .NET) you would add ably-dotnet\src\Ably.PubSub.Core.NETFramework\Ably.PubSub.Core.NETFramework.csproj, and for .NET / .NET Standard you would add ably-dotnet\src\Ably.PubSub.Core\Ably.PubSub.Core.csproj.
 7. In any project that you want to use `ably-dotnet` you need to add a project reference, to do so:
     1. Find your project in Solution Explorer and expand the tree so that the Dependencies node is visible
     2. Right click Dependencies and select Add Reference
-    3. In the dialogue that opens you should see a list of the projects in your solution. Check the box next to IO.Ably.NETFramework (or whatever version you are trying to use) and click OK.
+    3. In the dialogue that opens you should see a list of the projects in your solution. Check the box next to Ably.PubSub.Core.NETFramework (or Ably.PubSub.Core, whichever you added) and click OK.
 
 ## Spec
 
@@ -111,9 +111,9 @@ This library uses [semantic versioning](http://semver.org/). For each release, t
 6. Push the branch and create a release PR (ensure you include an SDK Team Engineering Lead and the SDK Team Product Manager as reviewers) and gain approvals for it, then merge that to `main`.
 7. Go to [Github Actions tab](https://github.com/ably/ably-dotnet/actions), click on [Package Ably](https://github.com/ably/ably-dotnet/actions/workflows/package.yml) workflow at the left nav-bar. On the right corner, click on `Run workflow` with the current release tag as a input to `Ably version`.
   - You can check all latest workflows under [Github Actions Tab](https://github.com/ably/ably-dotnet/actions). Download the generated artifact named `output-package` at the end of the latest successful workflow run.
-  - `output-package` artifact is a zip with 4 files => `ably.io.1.2.3.nupkg`, `ably.io.push.android.1.2.3.nupkg`,`ably.io.push.ios.1.2.3.nupkg` and `ably.io.1.2.3.unitypackage`.
+  - `output-package` artifact is a zip containing => `Ably.PubSub.Core.2.0.0.nupkg` and `ably.pubsub.2.0.0.unitypackage`.
   - If using github codespaces, you can upload downloaded `output-package` artifact by dragging into it.
-8. Extract `output-package`, open bash/powershell in the same folder and run `dotnet nuget push ably.io.*.nupkg --api-key GENERATED_API_KEY_FROM_NUGET_ACCOUNT --source https://api.nuget.org/v3/index.json` (More information on publishing nuget package can be found [here](https://learn.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package-using-visual-studio?tabs=netcore-cli#publish-with-the-net-cli-or-nuget-cli))
+8. Extract `output-package`, open bash/powershell in the same folder and run `dotnet nuget push *.nupkg --api-key GENERATED_API_KEY_FROM_NUGET_ACCOUNT --source https://api.nuget.org/v3/index.json` (More information on publishing nuget package can be found [here](https://learn.microsoft.com/en-us/nuget/quickstart/create-and-publish-a-package-using-visual-studio?tabs=netcore-cli#publish-with-the-net-cli-or-nuget-cli))
 9. Add a tag to the new `main` head commit and push to origin such as `git tag 1.2.3 && git push origin 1.2.3`
-10. Visit [https://github.com/ably/ably-dotnet/tags](https://github.com/ably/ably-dotnet/tags) and `Add release notes` for the release including links to the changelog entry, upload `ably.io.1.2.3.unitypackage` as a file to the latest release note.
+10. Visit [https://github.com/ably/ably-dotnet/tags](https://github.com/ably/ably-dotnet/tags) and `Add release notes` for the release including links to the changelog entry, upload `ably.pubsub.1.2.3.unitypackage` as a file to the latest release note.
 11. Create the entry on the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/)).
diff --git a/PushNotifications.md b/PushNotifications.md
@@ -1,5 +1,12 @@
 # Push Notifications
 
+> [!IMPORTANT]
+> **This document describes the 1.x push-receive packages, which are not part of the 2.0 package set.**
+>
+> `ably.io.push.android` and `ably.io.push.ios` are Xamarin-era projects. They depend on `ably.io` 1.x, stay supported from the 1.x maintenance branch, and have been removed from this branch along with the `DotnetPush` and `AndroidSample` examples. A modern `Ably.PubSub.Push.Android` / `Ably.PubSub.Push.iOS` port on `net8.0-android` / `net8.0-ios`, built on `Ably.PubSub.Device`, is a post-GA 2.x follow-up; until it lands, a device application cannot combine the 2.0 SDK with Ably push receive.
+>
+> Push **administration** (`client.Push.Admin`) is unaffected: it lives in `Ably.PubSub.Core` and remains available.
+
 Push Notifications allow you to reach users irrespective of whether your application is running in the foreground, the background or has been terminated, even when your application is not connected to Ably.
 
 On iOS, Ably connects to [APNs](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html) to send messages to devices. On Android, Ably connects to [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/) to send messages to devices. As both services do not guarantee message delivery and may even throttle messages to specific devices based on battery level, message frequency, and other criteria, messages may arrive much later than sent or ignored.
@@ -219,7 +226,7 @@ Push notifications containing both the notification and data objects will be tre
 
 ### Receiving Messages
 
-For examples of handling incoming messages and dealing with notifications, see [push_notification_handlers](example/lib/push_notifications/push_notification_handlers.dart) in the example app.
+For examples of handling incoming messages and dealing with notifications, see the push samples under the `examples/` directory.
 
 #### Notification Message / Alert Push Notification
 

diff --git a/README.md b/README.md
@@ -1,5 +1,4 @@
 ![Ably Pub/Sub Dotnet Header](images/NETSDK-github.png)
-[![NuGet version](https://badge.fury.io/nu/ably.io.svg)](https://www.nuget.org/packages/ably.io)
 [![License](https://badgen.net/github/license/ably/ably-dotnet)](https://github.com/ably/ably-dotnet/blob/main/LICENSE)
 
 # Ably Pub/Sub .NET SDK
@@ -13,6 +12,27 @@ Find out more:
 * [Ably Pub/Sub docs.](https://ably.com/docs/basics)
 * [Ably Pub/Sub examples.](https://ably.com/examples?product=pubsub)
 
+> [!NOTE]
+> **2.0 is in development on this branch.**
+>
+> Ably Pub/Sub is being split into a device-side package and a server-side package, so that Ably can tell which side of an application a client belongs to. From 2.0 the .NET SDK ships as a set of NuGet packages:
+>
+> | Package | Use it for |
+> |---------|------------|
+> | `Ably.PubSub.Device` | End-user device applications (desktop, mobile, Unity, MAUI, browser-adjacent clients) — *added in the next PR in this stack* |
+> | `Ably.PubSub.Server` | Server-side and backend applications — *added in the next PR in this stack* |
+> | `Ably.PubSub.Core` | Internal implementation shared by the two packages above. Not intended for direct use; you receive it transitively |
+>
+> The compiled assembly is now `Ably.PubSub.Core.dll`. The code namespace is unchanged: `using IO.Ably;` and every public type name stay as they are for now.
+>
+> Today's [`ably.io`](https://www.nuget.org/packages/ably.io) 1.x package is unaffected and continues from a 1.x maintenance branch for a year after 2.0 becomes generally available; it is never published from this branch again. The same applies to `ably.io.push.android` and `ably.io.push.ios`, whose Xamarin-era projects are not part of the 2.0 set (see [PushNotifications.md](./PushNotifications.md)).
+>
+> Never reference `ably.io` and `Ably.PubSub.*` from the same project: they share the `IO.Ably` namespace, so mixing them is a compile error by design.
+>
+> This also applies **transitively**. NuGet dedupes only by package ID, so a graph that pulls both `ably.io` 1.x (often via a library dependency) and any `Ably.PubSub.*` package loads *both* assemblies, and every `IO.Ably.*` type then exists twice: you get compile error CS0433 where your own code names those types, and runtime type-identity failures (`InvalidCastException`-class) where a library exposes `IO.Ably` types across its API. There is no type-forwarding between the packages. Detect it with `dotnet nuget why <project> ably.io`; if a dependency genuinely forces both, isolate them with an [`extern alias`](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/extern-alias) — note `<Aliases>` applies only to a **direct** `PackageReference`, so first promote `ably.io` to a direct reference of the affected project, then add `<Aliases>ablyLegacy</Aliases>` to it and `extern alias ablyLegacy;` in the consuming file — otherwise treat a both-packages graph as unsupported and migrate the transitive dependency off `ably.io`.
+>
+> The Installation and Usage sections below still describe the 1.x `ably.io` package; they are replaced with `Ably.PubSub.Device`/`Ably.PubSub.Server` instructions before 2.0 general availability.
+
 ---
 
 ## Getting started
@@ -32,14 +52,11 @@ Everything you need to get started with Ably:
 | .NET | 6.0+, .NET Core 2.0+ |
 | .NET Framework | 4.6.2+ |
 | Mono | 5.4+ |
-| Xamarin.Android | 8.0+ |
-| Xamarin.iOS | 10.14+ |
-| Xamarin.Mac| 3.8+ |
+| .NET for Android, .NET for iOS and MAUI | via `netstandard2.0` |
 | Unity | 2019.x+ |
-| MAUI | .NET 6.0+|
 
 > [!IMPORTANT]
-> SDK versions < 1.2.12 will be [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) from November 1, 2025.
+> SDK versions < 1.2.12 are [deprecated](https://ably.com/docs/platform/deprecate/protocol-v1) (protocol v1, retired November 1, 2025).
 
 ---
 
@@ -63,11 +80,11 @@ dotnet add package ably.io
 
 When using Ably in a MAUI project, be aware of potential issues caused by assembly trimming, as `ably-dotnet` relies on the reflection API. 
 
-Add the following to your `.csproj` file to prevent trimming of the `IO.Ably` assembly:
+Add the following to your `.csproj` file to prevent trimming of the Ably assembly:
 
 ```xml
 <ItemGroup>
-  <TrimmerRootAssembly Include="IO.Ably" />
+  <TrimmerRootAssembly Include="Ably.PubSub.Core" />
 </ItemGroup>
 ```
 
@@ -121,7 +138,7 @@ clientOpts.LogHandler = new CustomLogHandler();
 
 ### Unity usage
 
-- Download latest `ably.io.*.unitypackage` from [releases section](https://github.com/ably/ably-dotnet/releases) and include it in the unity project.
+- Download latest `ably.pubsub.*.unitypackage` from [releases section](https://github.com/ably/ably-dotnet/releases) and include it in the unity project.
 - For more information, check [Unity README](./unity/README.md)
 
 ## Releases