HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/release-note/upgrading-to-3.2/session-project-and-commands.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
      <title>Session, project and command model | HiAPI-C# 2025 </title>
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta name="title" content="Session, project and command model | HiAPI-C# 2025 ">
      
      
      <link rel="icon" href="../../img/HiAPI.favicon.ico">
      <link rel="stylesheet" href="../../public/docfx.min.css">
      <link rel="stylesheet" href="../../public/main.css">
      <meta name="docfx:navrel" content="../../toc.html">
      <meta name="docfx:tocrel" content="toc.html">
      
      <meta name="docfx:rel" content="../../">
      
      
      
      <meta name="loc:inThisArticle" content="In this article">
      <meta name="loc:searchResultsCount" content="{count} results for &quot;{query}&quot;">
      <meta name="loc:searchNoResults" content="No results for &quot;{query}&quot;">
      <meta name="loc:tocFilter" content="Filter by title">
      <meta name="loc:nextArticle" content="Next">
      <meta name="loc:prevArticle" content="Previous">
      <meta name="loc:themeLight" content="Light">
      <meta name="loc:themeDark" content="Dark">
      <meta name="loc:themeAuto" content="Auto">
      <meta name="loc:changeTheme" content="Change theme">
      <meta name="loc:copy" content="Copy">
      <meta name="loc:downloadPdf" content="Download PDF">

      <script type="module" src="./../../public/docfx.min.js"></script>

      <script>
        const theme = localStorage.getItem('theme') || 'auto'
        document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme)
      </script>

  </head>

  <body class="tex2jax_ignore" data-layout="" data-yaml-mime="">
    <header class="bg-body border-bottom">
      <nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
        <div class="container-xxl flex-nowrap">
          <a class="navbar-brand" href="../../index.html">
            <img id="logo" class="svg" src="../../img/HiAPI.logo.png" alt="">
            
          </a>
          <button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation">
            <i class="bi bi-three-dots"></i>
          </button>
          <div class="collapse navbar-collapse" id="navpanel">
            <div id="navbar">
              <form class="search" role="search" id="search">
                <i class="bi bi-search"></i>
                <input class="form-control" id="search-query" type="search" disabled placeholder="Search" autocomplete="off" aria-label="Search">
              </form>
            </div>
          </div>
        </div>
      </nav>
    </header>

    <main class="container-xxl">
      <div class="toc-offcanvas">
        <div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel">
          <div class="offcanvas-header">
            <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
            <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="Close"></button>
          </div>
          <div class="offcanvas-body">
            <nav class="toc" id="toc"></nav>
          </div>
        </div>
      </div>

      <div class="content">
        <div class="actionbar">
          <button class="btn btn-lg border-0 d-md-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas" aria-controls="tocOffcanvas" aria-expanded="false" aria-label="Show table of contents">
            <i class="bi bi-list"></i>
          </button>

          <nav id="breadcrumb"></nav>
        </div>

        <article data-uid="Release-Upgrading-SessionModel">
          <h1 id="session-project-and-command-model">Session, project and command model</h1>

<ul>
<li><strong>A parser and its per-case data travel as one file.</strong> <a class="xref" href="../../api/Hi.NcParsers.NcRunnerSuit.html">NcRunnerSuit</a> bundles a
runner with the dependency data a particular job needs, as a single file-loadable unit. The project
holds three suits — <a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html#Hi_MachiningProcs_MachiningProject_NcRunnerSuit">NcRunnerSuit</a>,
<a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html#Hi_MachiningProcs_MachiningProject_CsvRunnerSuit">CsvRunnerSuit</a> and
<a class="xref" href="../../api/Hi.MachiningProcs.MachiningProject.html#Hi_MachiningProcs_MachiningProject_ClsfRunnerSuit">ClsfRunnerSuit</a> — and
<a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_ReadNcRunnerSuit_">ReadNcRunnerSuit</a> /
<a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_WriteNcRunnerSuit_">WriteNcRunnerSuit</a> switch the active parser mid-project
from a suit file. A switch attempted while a program is playing is refused with
<code>ReadNcRunnerSuit--Refused</code>.</li>
<li><strong>One NC runner configuration is shareable across projects.</strong> Per-case data — tool offsets,
work-coordinate offsets, Siemens frames, Heidenhain datums, retained macro variables, seeded brand
parameter tables — travels as proxy placeholders inside <a class="xref" href="../../api/Hi.NcParsers.SoftNcRunner.html">SoftNcRunner</a> and
resolves against the owning project's per-case list, so a controller configuration is no longer
welded to the job it was first built for. Machine-config consumers read the resolved view through
<a class="xref" href="../../api/Hi.NcParsers.SoftNcRunner.html#Hi_NcParsers_SoftNcRunner_GetEffectiveNcDependencyList_">GetEffectiveNcDependencyList</a>; legacy <code>&lt;NcDependencyList&gt;</code> XML and
<code>NcEnv</code>-based projects still load and migrate automatically.</li>
<li><strong>HTTP guards and one envelope.</strong> <a class="xref" href="../../api/Hi.MachiningProcs.RequireActiveSessionAttribute.html">RequireActiveSessionAttribute</a> answers a
session-scoped action with HTTP 409 and an <code>ApiActionResult.NoActiveSession()</code> body when no session is
active, instead of the previous null-reference 500;
<a class="xref" href="../../api/Hi.MachiningProcs.RequireLoadedProjectAttribute.html">RequireLoadedProjectAttribute</a> does the same for the project-level controller.
Both are applied at the controller level and honour opt-out markers
(<a class="xref" href="../../api/Hi.MachiningProcs.AllowNoActiveSessionAttribute.html">AllowNoActiveSessionAttribute</a>,
<a class="xref" href="../../api/Hi.MachiningProcs.AllowNoLoadedProjectAttribute.html">AllowNoLoadedProjectAttribute</a>). Mutating actions inject a fresh
<a class="xref" href="../../api/Hi.Common.Messages.MessageCollector.html">MessageCollector</a> and return the collected notifications inline in the
shared <a class="xref" href="../../api/Hi.MachiningProcs.ApiActionResult.html">ApiActionResult</a> envelope, so a REST or AI caller sees progress,
success and error messages in the response instead of only out of band.
<a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectServiceController.html">LocalProjectServiceController</a> exposes the project-level (session-independent)
surface parallel to <a class="xref" href="../../api/Hi.MachiningProcs.SessionShellController.html">SessionShellController</a>.</li>
<li><strong>Session commands declare themselves.</strong> <a class="xref" href="../../api/Hi.SessionCommands.CommandCatalogAttribute.html">CommandCatalogAttribute</a> marks an
<a class="xref" href="../../api/Hi.SessionCommands.ISessionCommand.html">ISessionCommand</a> as user-addable and places it in a
<a class="xref" href="../../api/Hi.SessionCommands.CommandCategory.html">CommandCategory</a> (Setup / Program / Optimization / Output / Flow, declaration
order = display order) with an <code>Order</code> sort key and an optional wire kind (default: the class name
minus the <code>Command</code> suffix, lower-cased). <a class="xref" href="../../api/Hi.SessionCommands.CommandFieldAttribute.html">CommandFieldAttribute</a> marks a
bool / int / double / string property as a directly editable scalar with an optional label, unit and
physics-licence flag, so a generic editor renders and updates it without a hand-written form. A
command without the catalog attribute stays loadable from project files but is not offered for
creation.</li>
<li><strong>Program File dispatches by kind.</strong> <a class="xref" href="../../api/Hi.SessionCommands.NcFileCommand.html">NcFileCommand</a> gains an <code>NcKind</code>
property (XML element <code>NcKind</code>, absent = <code>Auto</code> for legacy projects) and its mission label becomes
&ldquo;Program File&rdquo;; each command resolves its own file, so a List of Program Files can mix
brand NC, CL and CSV.</li>
<li><strong>Two session commands saved but could never be read back.</strong> <code>ListCommand.Reg</code> chained every type
except <a class="xref" href="../../api/Hi.SessionCommands.NcOptOptionCommand.html">NcOptOptionCommand</a> and
<a class="xref" href="../../api/Hi.SessionCommands.RecordMeshedGeomCommand.html">RecordMeshedGeomCommand</a>, so any XML round-trip of an entry holding one threw
<code>KeyNotFoundException</code> out of the <a class="xref" href="../../api/Hi.Common.XmlUtils.XFactory.html">XFactory</a> generator lookup — reloading a
saved project containing an NC Optimization Config command failed. Both are now chained.</li>
<li><strong>Naming.</strong> <a class="xref" href="../../api/Hi.SessionCommands.ListCommand.html#Hi_SessionCommands_ListCommand_Title">Title</a> is an optional name shown in place of the type
name, so nested command lists can be named in the mission tree. <code>PreSettingCommand</code> displays as
&ldquo;General Config&rdquo; and <code>NcOptOptionCommand</code> as &ldquo;NC Optimization Config&rdquo; — display strings only, so
serialization and endpoints are untouched. A bare non-list <code>PlayerCommand</code> root is normalized on read
into a single enabled entry of the default <code>ListCommand</code>. Command titles, catalog categories and field
labels are now localized, and a zh-Hans resource set was created (none existed before). Default-script
template keys stay untranslated on purpose — they compose the C# comments and script title written
into the user's <code>.hincproj</code>, which travels to other machines.</li>
<li><strong>Script faults are keyed errors.</strong> A <code>CompilationErrorException</code> or a faulted script task used to
surface as an anonymous warning; <a class="xref" href="../../api/Hi.SessionCommands.ScriptCommand.html">ScriptCommand</a> now reports
<code>ScriptCommand-Compile--Failed</code> with the full diagnostic list and <code>ScriptCommand-Run--Fault</code> with the
exception, both at Error severity.</li>
<li><strong>A fresh session re-homes the machining chain.</strong> <code>ResetRuntime</code> wrote the configured XYZ home but
hard-coded ABC to 0, and it only ran on project switch or pace-player reset — never before a plain
Play. A freshly loaded project therefore started from whatever pose the <code>.mt</code> happened to serialize,
while the act stream interpolated from the home seed, so the first contour swept from a pose the
machine was never at and cut along the way. The re-home now reads the rotary homes from the same home
configuration and also runs at <a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_BeginSession_">BeginSession</a>; a
mid-session replay is untouched.</li>
<li><strong>What a reset actually resets.</strong> <a class="xref" href="../../api/Hi.MachiningProcs.SessionShell.html#Hi_MachiningProcs_SessionShell_ResetRuntime_">ResetRuntime</a> now also
rewinds the NC-runner session state, so the next play restarts file and line indexing from scratch
the way <code>PowerReset</code> does, and it resets the CL device pose to identity. It no longer clobbers
<code>MachiningResolution_mm</code>: the runtime resolution is seeded from the workpiece's initial resolution
only when a project loads, so an explicit override survives a runtime reset and a workpiece swap.</li>
<li><strong>Mixed runner kinds in one session are refused.</strong> <code>NcRunnerSessionState</code> remembers the runner that
initialised it and <a class="xref" href="../../api/Hi.NcParsers.SoftNcRunner.html#Hi_NcParsers_SoftNcRunner_RunNcLines_">RunNcLines</a> refuses a different one with
<code>RunNcLines--RunnerMismatch</code> — reachable now that <code>NcKind.Auto</code> makes mixed-kind missions a
first-class flow.</li>
<li><strong>Stale state on a chain or project switch.</strong> Building the coordinate converter nulls the rotary
solver when the chain is not an <code>IXyzabcChain</code>, so a solver built for the old machine no longer keeps
converting after a switch to a CL device; and
<a class="xref" href="../../api/Hi.NcMech.Workpieces.WorkpieceService.html#Hi_NcMech_Workpieces_WorkpieceService_ClearCache_">ClearCache</a> now also calls
<a class="xref" href="../../api/Hi.NcMech.Workpieces.WorkpieceService.html#Hi_NcMech_Workpieces_WorkpieceService_ClearIdealGeomCache_">ClearIdealGeomCache</a>, so loading another project stops
rendering the previous project's target geometry.</li>
<li><strong>Project-file operations are serialized through a zero-wait gate.</strong> A New / Load / Save / Reload
/ Close arriving while another is in progress throws
<a class="xref" href="../../api/Hi.MachiningProcs.ProjectFileBusyException.html">ProjectFileBusyException</a> immediately instead of racing into a file-in-use
<code>IOException</code>. Close was the one operation left outside the gate, so a Close arriving during a Save
could let the Save finish without writing and still return 200; it now refuses with the same 409
the other five ops already used.</li>
<li><strong><a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_LoadProject_">LoadProject</a> and
<a class="xref" href="../../api/Hi.MachiningProcs.LocalProjectService.html#Hi_MachiningProcs_LocalProjectService_ReloadProject_">ReloadProject</a> take a message sink</strong> for load-time
diagnostics (a referenced STL missing on disk, a child XML that will not deserialize). A load-time
diagnostic does not fail the load; passing no sink leaves the application log as the only witness.
See <a class="xref" href="../../technique/api-foundations/message-management.html">Message Management</a>.</li>
<li><strong><a class="xref" href="../../api/Hi.Machining.MachiningEquipmentUtils.MachiningEquipmentUtil.html#Hi_Machining_MachiningEquipmentUtils_MachiningEquipmentUtil_AlignWorkpieceProgramZeroToIso_">AlignWorkpieceProgramZeroToIso</a>
computes in the machine-zero state.</strong> It reflects the assembly and zeroes every dynamic axis before
querying displacements, so the alignment is correct even when the live machine's axes are
displaced.</li>
<li><strong><a class="xref" href="../../api/Hi.Common.PacePlayer.html#Hi_Common_PacePlayer_RunCount">RunCount</a></strong> counts runs started, incremented synchronously before the
run's task launches and never reset. Pairing it with <code>IsFinished</code> in one snapshot lets a polling
client distinguish &ldquo;the run I started has finished&rdquo; from a stale Finished left by a previous run.</li>
</ul>

</article>

        <div class="contribution d-print-none">
        </div>

        <div class="next-article d-print-none border-top" id="nextArticle"></div>

      </div>

      <div class="affix">
        <nav id="affix"></nav>
      </div>
    </main>

    <div class="container-xxl search-results" id="search-results"></div>

    <footer class="border-top text-secondary">
      <div class="container-xxl">
        <div class="flex-fill">
          <span> Copyright © 2025 <a href='https://superhightech.com.tw'>Tech Coordinate</a>. All rights reserved. <a href='https://superhightech.com.tw'>超級高科技股份有限公司</a> © 2025 版權所有 </span>
        </div>
      </div>
    </footer>
  </body>
</html>