HiNC-Deploy/HiNC-2025-win-desktop-Deploy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

tune

Browse Source
This commit is contained in:
iamboss
2025-09-15 16:51:51 +08:00
parent 6a4e515562
commit a69e02dd26
29 changed files with 319 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
App/wwwroot/HiAPI-docsite/brief/dev-doc/basic/common/xml-io.html
+5 -34
View File
@@ -87,7 +87,7 @@
<article data-uid="">
<h1 id="about-xml-io">About XML IO</h1>
<p>The XML IO design pattern in Hi Framework is based on <a class="xref" href="../../../../api/Hi.Common.XmlUtils.IMakeXmlSource.html">IMakeXmlSource</a> interface and <a class="xref" href="../../../../api/Hi.Common.XmlUtils.XFactory.html">XFactory</a> class. This pattern provides a standardized way to serialize and deserialize objects to and from XML format.</p>
<p>The XML IO design pattern in HiNc Framework is based on <a class="xref" href="../../../../api/Hi.Common.XmlUtils.IMakeXmlSource.html">IMakeXmlSource</a> interface and <a class="xref" href="../../../../api/Hi.Common.XmlUtils.XFactory.html">XFactory</a> class. This pattern provides a standardized way to serialize and deserialize objects to and from XML format.</p>
<p>Don't serialize the runtime member object like <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.func-1">Func&lt;TResult&gt;</a> or <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.action">Action</a> either cache object. The runtime objects can be optionally sent by the res part on the XFactory Registration or set by the other host or dependent object. If it is set by the other object, then there is nothing can do to it in the XML IO procedure.</p>
<h2 id="core-components">Core Components</h2>
<h3 id="imakexmlsource-interface">IMakeXmlSource Interface</h3>
@@ -95,7 +95,7 @@
<h3 id="xfactory-registration">XFactory Registration</h3>
<p>Every class implementing IMakeXmlSource must:</p>
<ol>
<li>Define a static XName property matching the class name</li>
<li>Define a static XName property matching the class name.</li>
<li>Register itself in the static constructor using XFactory.Regs.Add</li>
<li>Implement XML serialization and deserialization logic</li>
</ol>
@@ -271,41 +271,12 @@ public XElement MakeXmlSource(string baseDirectory, string relFile, bool exhibit
}
</code></pre><h2 id="best-practices">Best Practices</h2>
<ol>
<li><strong>XName</strong>: Always define static XName property matching the class name</li>
<li><strong>Registration</strong>: Register in static constructor using XFactory.Regs.Add</li>
<li><strong>XName</strong>: Always define static XName property matching the class name.</li>
<li><strong>Registration</strong>: Register in static constructor using <a class="xref" href="../../../../api/Hi.Common.XmlUtils.XFactory.html">XFactory</a>.Regs</li>
<li>Call the XName such like <code>_ = CalleeClass.XName;</code> in the caller class static initailization field so that the registration takes effect before calling the Callee construction by <a class="xref" href="../../../../api/Hi.Common.XmlUtils.XFactory.html">XFactory</a>.</li>
<li><strong>Error Handling</strong>: Use appropriate <a class="xref" href="../../../../api/Hi.Common.XmlUtils.GenMode.html">GenMode</a></li>
<li><strong>Legacy Support</strong>: Maintain backward compatibility when needed</li>
<li><strong>Documentation</strong>: Include XML comments for properties and methods</li>
</ol>
<h2 id="generation-modes">Generation Modes</h2>
<p>The <a class="xref" href="../../../../api/Hi.Common.XmlUtils.GenMode.html">GenMode</a> enumeration provides:</p>
<ul>
<li><a class="xref" href="../../../../api/Hi.Common.XmlUtils.GenMode.html#Hi_Common_XmlUtils_GenMode_None">None</a></li>
<li><a class="xref" href="../../../../api/Hi.Common.XmlUtils.GenMode.html#Hi_Common_XmlUtils_GenMode_Catch">Catch</a></li>
<li><a class="xref" href="../../../../api/Hi.Common.XmlUtils.GenMode.html#Hi_Common_XmlUtils_GenMode_Rebase">Rebase</a></li>
<li><a class="xref" href="../../../../api/Hi.Common.XmlUtils.GenMode.html#Hi_Common_XmlUtils_GenMode_Default">Default</a></li>
</ul>
<h2 id="common-usage-patterns">Common Usage Patterns</h2>
<ol>
<li><strong>Simple Object Generation</strong>:</li>
</ol>
<pre><code class="lang-csharp">var obj = XFactory.Gen&lt;MyType&gt;(xmlElement, baseDir, null, GenMode.Default);
</code></pre>
<ol start="2">
<li><strong>File-Based Generation</strong>:</li>
</ol>
<pre><code class="lang-csharp">var obj = XFactory.GenByFile&lt;MyType&gt;(baseDir, relativeFile, GenMode.Default);
</code></pre>
<ol start="3">
<li><strong>XML Source and File Generation</strong>:</li>
</ol>
<pre><code class="lang-csharp">var xmlSourceAndFile = XFactory.GenXmlSourceAndFile&lt;MyType&gt;(xmlElement, baseDir, null, GenMode.Default);
</code></pre>
<ol start="4">
<li><strong>Hierarchical Object Generation</strong>:</li>
</ol>
<pre><code class="lang-csharp">var childObj = XFactory.GenByChild&lt;IStructureMaterial&gt;(parentElement, baseDir, null, GenMode.Default);
</code></pre>
</article>