Auto: ablegacy-11 — RSLogix 500/PLC-5 CSV symbol import

Closes #254
2026-04-26 04:13:13 -04:00
parent 4fdeef7a6c
commit 4e8df38bb2
19 changed files with 1644 additions and 0 deletions
@@ -0,0 +1,40 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Import;
+
+/// <summary>
+///     Materialises <see cref="AbLegacyTagDefinition"/> entries from a RSLogix export. v1 ships
+///     a single implementation (<see cref="RsLogixSymbolImport"/>) for text/CSV "Database
+///     Export" — RSLogix 500's <c>.RSS</c> and RSLogix 5's <c>.RSP</c> binary project files are
+///     proprietary and out of scope (no parser ships with libplctag or any community library at
+///     the time of writing). The interface exists so a binary parser can slot in later without
+///     reshaping the call sites.
+/// </summary>
+/// <remarks>
+///     <para>
+///         The <c>deviceHostAddress</c> parameter on <see cref="Parse"/> is required because RSLogix
+///         exports list addresses scoped to a single PLC; the importer needs to stamp every
+///         resulting tag with the gateway address that the runtime layer will use to reach
+///         it. Multi-device deployments call the importer once per device, then concatenate.
+///     </para>
+///     <para>
+///         <see cref="Parse"/> never throws on parse errors when
+///         <see cref="ImportOptions.IgnoreInvalid"/> is <c>true</c> (default) — malformed rows
+///         are skipped with a structured warning logged via the importer's <c>ILogger</c>, and
+///         the counts surface on <see cref="RsLogixImportResult"/>. With
+///         <see cref="ImportOptions.IgnoreInvalid"/> set to <c>false</c> the first malformed row
+///         throws <see cref="System.IO.InvalidDataException"/>.
+///     </para>
+/// </remarks>
+public interface IRsLogixImporter
+{
+    /// <summary>
+    ///     Read the entire <paramref name="stream"/> and emit one
+    ///     <see cref="AbLegacyTagDefinition"/> per recognised symbol row.
+    /// </summary>
+    /// <param name="stream">Open, readable stream over the RSLogix export. Caller owns it.</param>
+    /// <param name="deviceHostAddress">
+    ///     Canonical AB Legacy gateway URI (<c>ab://host[:port]/cip-path</c>) the resulting
+    ///     tags should bind to.
+    /// </param>
+    /// <param name="options">Filter + safety knobs; <c>null</c> ≡ default options.</param>
+    RsLogixImportResult Parse(Stream stream, string deviceHostAddress, ImportOptions? options = null);
+}