Repository navigation
Add GETTING_STARTED_V1.6.md beta guide - #8703
Merged
Aaronontheweb merged 2 commits intoOct 1, 2026
Merged
Conversation
The Akka.NET website stays on v1.5 docs until v1.6 stabilizes, so beta users need a guide that lives in the repo. Covers what changed in v1.6 (net10.0-only, Akka.Hosting now shipping from this repo, Artery, the V2 source-generated serializer, and Native AOT support), with a getting-started sample for Akka.Hosting, the Setup APIs that replace HOCON type names under Native AOT, a working Akka.Serialization.V2 sample, and the HOCON to turn on Artery. Adds "netstandard" to the cspell dictionary used by the new page.
…witch An Opus review that actually restored and built the samples found several problems: the *-beta* version wildcard silently resolves to the 1.5.71 release on NuGet instead of failing, so readers following the Hosting sample would get v1.5 without knowing it; the Hosting sample needs an explicit Microsoft.Extensions.Hosting package reference for Host.CreateApplicationBuilder, which Akka.Hosting itself doesn't carry; and the AOT csproj snippet copied the canary's RID-conditioned property group, which silently skips AOT when a reader runs `dotnet publish` without `-r`. Switches every package reference to `1.6.0-beta*` (fails loudly with NU1102 until a real beta ships, instead of quietly restoring 1.5), reorders the Hosting sample so the package step comes first, simplifies the AOT csproj snippet to just PublishAot=true plus a separate note about the ProjectReference-only switch, and corrects several other claims a closer read of the source turned up: classic DotNetty remoting does not work at all under Native AOT (Artery is the target, confirmed by one manual probe, not a CI canary); ActorSystemSetup keeps one setup per type, so a second SerializationSetup replaces rather than merges; Akka.Hosting's AddSetup composes with the V2 serializer but WithCustomSerializer silently replaces it; Artery logs its own "don't use in production" warning and changes the address scheme and default port; and the field-index diagnostics are AKKASG005/AKKASG026, not a blanket "missing index" rule. Adds an "Upgrading from 1.5" note on third-party plugin compatibility and the ledger's Wire rows. Re-verified by rebuilding all three C# samples (Hosting, the combined Setup APIs, and the V2 serializer) from the doc text verbatim, plus a standalone check that `*-beta*` resolves to Akka 1.5.71 while `1.6.0-beta*` fails with NU1102, and that the simplified AOT csproj snippet produces zero trim/AOT warnings with the manual switch and many without it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
The Akka.NET website is frozen on v1.5 docs until v1.6 stabilizes. Beta users
have no in-repo guide to work from. This PR adds one:
GETTING_STARTED_V1.6.mdat the repo root, rendered directly on GitHub, plus a short pointer to it near
the top of
README.md.Merge order: merge this after #8701. #8701 refreshes
docs/articles/deployment/native-aot.md, which the Native AOT section herelinks to for details - on
devtoday that page is stale relative to the AOTwork that already landed.
Sections
repo (package ids, the version-alignment requirement,
Microsoft.Extensions.*10.0.0 floor), Artery, the source-generated V2 serializer, and Native AOT
support in progress. Links
BREAKING_CHANGES_V1.6.md.the ledger's
Wirerows before a rolling upgrade.the
Microsoft.Extensions.HostingpackageAkka.Hostingitself doesn'tcarry) and a minimal
Host.CreateApplicationBuilder+AddAkkasample.ActorSystemand an Akka.Hosting app, both
PublishAot), what's only been manuallyprobed (Remote over Artery - classic DotNetty does not work under AOT at
all), what's unsupported for now (Cluster, Persistence, cluster tools), the
SetupAPIs that replace HOCON type names (and their one-setup-per-typegotcha), and the stream-refs/manifest-serializer exceptions. Links the
fuller
docs/articles/deployment/native-aot.mdfor details instead ofrepeating it.
protocol interface, message type, serializer declaration, registration, and
how it composes (or doesn't) with Akka.Hosting's
AddSetup/WithCustomSerializer.Links
docs/articles/serialization/source-generated-serialization.mdforthe full reference.
warning Akka.NET logs itself, the address-scheme/port change, and the one
supported transport.
Verification
in the Native AOT section, and the
Akka.Serialization.V2sample) were builtand run as standalone console apps referencing the real projects in this repo
(
Akka.csproj,Akka.Hosting.csproj,Akka.Serialization.V2.csproj+its generator wired in as an analyzer, the same way
Akka.Remote.csprojdoes). Each one compiled and produced the expected output; the code in the
doc is an exact subset of what ran - re-verified again after a round of
review fixes by rebuilding from the final doc text verbatim.
PublishAot=truealone (noRuntimeIdentifiercondition) against aProjectReferencetoAkka.csprojproduces ~20 IL2026/IL2067/etc. trim warnings on
dotnet publish; adding<RuntimeHostConfigurationOption Include="Akka.DynamicTypeLoading" Value="false" Trim="true" />reduces that to zero and the published nativebinary runs correctly.
Version="*-beta*"resolvesto
Akka 1.5.71ondotnet restore(confirmed viaproject.assets.json);Version="1.6.0-beta*"fails withNU1102as intended.builder.AddSetup(registration.CreateSetup())from Akka.Hosting, composedwith a source-generated
Akka.Serialization.V2serializer, was built and runend to end.
AotCanaryCI job,the
Akka.DynamicTypeLoadingswitch, Artery's HOCON/transport support andits runtime warning/address scheme, the generator's diagnostics) was checked
against the current
devsource, not assumed.markdownlint(same config as CI's.markdownlint.json) andcspell(CI'sdocs/cSpell.json) both run clean against the new file and the READMEchange, and the full
docs/**/*.mdtree still passes after the dictionaryaddition. Note: CI's own lint/spellcheck jobs only glob
docs/**/*.md, sothese two root-level files aren't covered by CI - I ran both tools locally
against them anyway and added
netstandardto the shared dictionary.Test plan
GETTING_STARTED_V1.6.mdon GitHub and confirm the in-page anchorlinks resolve