pe-deployment-1700tokens.txt

# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
=== ProEssentials Deployment (knowledge rev 1) ===

What actually has to ship. The developer machine lies -- it already has
runtimes and registrations a customer machine does not. Always test on a
clean machine.

REDISTRIBUTABLES -- THE ENGINE ITSELF
  Roughly 7 MB, one or two files (the engine DLL for the target architecture).
  Charts run on systems with as little as 1 GB of memory.
  For .NET, also ship the ProEssentials assembly for the chosen flavor.

*** WinUI 3 UNPACKAGED -- THE PART THAT SURPRISES PEOPLE ***
  An unpackaged WinUI 3 app is NOT a single EXE. You must ship the WHOLE
  output folder, and the customer needs TWO runtimes installed:
    1. .NET Desktop Runtime (matching the target framework)
    2. Windows App SDK Runtime
  There is a floor of roughly 30 projection DLLs in the folder. Do not try to
  hand-prune them.
  MSIX packaging is Microsoft's clean path and avoids the runtime prerequisite
  problem, at the cost of packaging and signing.

*** .pri IS REQUIRED -- MISSING IT IS A SILENT, BRUTAL FAILURE ***
  If the WinUI resource index (.pri) is missing, the chart RENDERS NOTHING.
  The control still constructs, Loaded still fires, breakpoints still hit --
  it simply draws nothing. If a WinUI chart is blank and no exception was
  thrown, CHECK FOR THE .pri FIRST.

LEAN PACKAGING (WinUI)
  Reference the Windows App SDK COMPONENT packages, not the umbrella package.
  The umbrella drags in AI/ML/ONNX content (tens of megabytes) that a charting
  application never uses.

VISUAL STUDIO TRAPS
  NO XAML DESIGNER FOR WinUI 3. Visual Studio does not support a XAML design
  surface for WinUI 3 in any version, including 2026. The Toolbox is empty by
  design. This is a Microsoft gap and affects every vendor's controls equally.
  NEVER tell a developer to "drag the control from the Toolbox" for WinUI.
  Create the control in XAML or in code instead.

  VS WinUI project templates default to PACKAGED. Running the raw EXE from a
  packaged template fails with REGDB_E_CLASSNOTREG. For unpackaged output set
  WindowsPackageType=None.

  VS WinUI templates also default to net8, not net10. Retarget deliberately,
  and watch for legacy win10-* RIDs causing NETSDK1083.

DESIGN-TIME (WinForms and WPF)
  The designer loads controls in a DIFFERENT host process depending on target:
    .NET Framework WinForms/WPF -- devenv.exe
    .NET Core WinForms          -- out-of-process DesignToolsServer
    WPF (Core)                  -- devenv.exe
    WinUI                       -- no designer at all
  This is why an AnyCPU flavor may extract its engine to %LOCALAPPDATA% at
  design time. For robust design-time behavior, gate code with
  LicenseManager.UsageMode == LicenseUsageMode.Designtime.

Related: pe-platform-targeting (which build), pe-embedded-iot (device targets).