Add documentation for Twin Identity System and update table of contents

Author: PTKu

docfx/articles/connectors/IDENTITY.md

@@ -0,0 +1,64 @@
+# Twin Identity System
+
+## Overview
+
+The identity system in AXSharp allows twin objects to be looked up by a unique numeric identity (`ulong`). This is used by components that need to resolve references between twin objects at runtime (e.g. the `[MemberByIdentity]` attribute).
+
+The core class is [`TwinIdentityProvider`](~/api/AXSharp.Connector.Identity.TwinIdentityProvider.yml), which is responsible for assigning, writing, and sorting identity values.
+
+## How identities work
+
+1. During twin construction, each object that implements `ITwinIdentity` is registered via `AddIdentity`.
+2. When the application starts, `ConstructIdentitiesAsync` is called to assign identity values, write them to the PLC, and build a sorted lookup dictionary.
+3. Other parts of the system can then resolve objects by their identity using `GetTwinByIdentity`.
+
+## Constructing identities
+
+```csharp
+await connector.IdentityProvider.ConstructIdentitiesAsync();
+```
+
+`ConstructIdentitiesAsync` performs the following steps:
+
+1. **Assign** -- Each identity tag is assigned a `ulong` value using the provided `identityProvider` function. If no function is supplied, a default provider based on `string.GetHashCode()` of the symbol is used.
+2. **Write** -- The assigned values are written to the PLC via `WriteBatchAsync`. Values are always written fresh, regardless of what was previously stored on the PLC.
+3. **Sort** -- The identities are sorted into a `SortedDictionary<ulong, ITwinIdentity>` using the locally assigned values (`Cyclic`), not values read back from the PLC.
+
+This ensures that stale or inconsistent identity values left on the PLC from prior sessions cannot cause errors.
+
+## The `failOnDuplicate` parameter
+
+```csharp
+await connector.IdentityProvider.ConstructIdentitiesAsync(failOnDuplicate: false);
+```
+
+By default, `ConstructIdentitiesAsync` throws a `DuplicateIdentityException` when two symbols resolve to the same identity value. You can set `failOnDuplicate` to `false` to log a warning and skip the duplicate entry instead.
+
+## Custom identity providers
+
+The default identity provider uses `string.GetHashCode()`, which has two important limitations:
+
+- **Not deterministic across processes** -- In .NET Core/.NET 5+, `string.GetHashCode()` is randomized per process. Identity values will differ between application restarts.
+- **Collision risk** -- `GetHashCode()` returns a 32-bit value. For large PLC programs with many symbols, hash collisions become increasingly likely (birthday paradox).
+
+For production use, supply a custom identity provider that guarantees uniqueness:
+
+```csharp
+await connector.IdentityProvider.ConstructIdentitiesAsync(
+    identityProvider: tag => tag.Cyclic = MyStableHashFunction(tag.Symbol)
+);
+```
+
+A good custom provider should:
+- Produce deterministic values for the same symbol across process restarts.
+- Guarantee uniqueness (or near-uniqueness) across all symbols in the program.
+- Use the full 64-bit `ulong` range to minimize collision probability.
+
+## Troubleshooting
+
+### `DuplicateIdentityException`
+
+This exception is thrown when two different symbols are assigned the same identity value. Common causes:
+
+- **Hash collision** with the default `GetHashCode()`-based provider. Solution: use a custom identity provider with better distribution, or set `failOnDuplicate: false` if identity-based lookups are not critical for your application.
+- **Stale PLC values** (resolved in current version) -- Previously, the identity system would read back values from the PLC after writing. If the PLC returned stale data from a prior session, this could cause spurious duplicate errors. The system now uses the locally assigned values directly, avoiding this issue.

docfx/articles/toc.yml

@@ -31,6 +31,8 @@
     href: ~/articles/connectors/Dummy.md
   - name: WebAPI
     href: ~/articles/connectors/WebAPI.md
+  - name: Identity
+    href: ~/articles/connectors/IDENTITY.md
 - name: Blazor rendering
   href: ~/articles/blazor/README.md
   items:

src/AXSharp.connectors/src/AXSharp.Connector/Identity/TwinIdentityProvider.cs

@@ -234,11 +234,20 @@ public async Task WriteIdentities(IEnumerable<OnlinerULInt> identitiesToWrite)
     }
 
     /// <summary>
-    ///    Constructs identities by assigning them locally and writing to PLC, then sorts them by their assigned values.
+    ///    Constructs identities by assigning them locally, writing to PLC, and sorting by the assigned values.
+    ///    Identity values are always written fresh to the PLC regardless of any previously stored values.
+    ///    This ensures that stale or inconsistent identity values from prior sessions do not cause duplicate identity errors.
     /// </summary>
-    /// <param name="identityProvider">Function to provide identity values.</param>
-    /// <param name="failOnDuplicate">Indicates whether to fail on duplicate identities.</param>
-    /// <returns></returns>
+    /// <param name="identityProvider">
+    ///    Function that assigns and returns an identity value for each <see cref="OnlinerULInt"/> tag.
+    ///    When <c>null</c>, a default provider based on <see cref="string.GetHashCode()"/> of the symbol is used.
+    ///    Note: <see cref="string.GetHashCode()"/> is not deterministic across process restarts in .NET Core/.NET 5+,
+    ///    so identity values will differ between sessions. For stable identities, supply a custom provider.
+    /// </param>
+    /// <param name="failOnDuplicate">
+    ///    When <c>true</c>, throws <see cref="DuplicateIdentityException"/> if two symbols resolve to the same identity value.
+    ///    When <c>false</c>, logs a warning and skips the duplicate entry.
+    /// </param>
     public async Task ConstructIdentitiesAsync(Func<OnlinerULInt, ulong> identityProvider = null, bool failOnDuplicate = true)
     {
         await WriteIdentities(AssignIdentities(_identitiesTags, identityProvider));
@@ -283,39 +292,6 @@ internal async Task SortIdentitiesAsync(bool failOnDuplicate = true)
 
         _connector?.Logger.Information("Sorting identities done.");
     }
-
-    // /// <summary>
-    // ///     Sorts identities by reading values from PLC.
-    // /// </summary>
-    // internal async Task SortIdentitiesAsync()
-    // {
-    //     await Task.Run(async () =>
-    //     {
-    //         _connector?.Logger.Information("Sorting identities...");
-    //         if (_connector != null)
-    //         {
-    //             await _connector?.ReadBatchAsync(_identities.Select(p => p.Key), eAccessPriority.High);
-    //         }
-    //         _sortedIdentities.Clear();
-    //         foreach (var identity in _identities)
-    //         {
-    //             var key = identity.Key.LastValue;
-    //             if (!_sortedIdentities.ContainsKey(key))
-    //             {
-    //                 _sortedIdentities.Add(key, identity.Value);
-    //             }
-    //             else
-    //             {
-    //                 throw new DuplicateIdentityException("There is a duplicate identity: " +
-    //                                                      $"{identity.Value.Symbol} : {key}." +
-    //                                                      $"The algorithm for assigning identities needs to be adjusted." +
-    //                                                      $"Use an algorithm that guarantees unique identities and is less prone to collisions.");
-    //             }
-    //         }
-
-    //         _connector?.Logger.Information("Sorting identities done.");
-    //     });
-    // }
 }
 
 /// <summary>