Deployment and Startup Notes (MxServiceCode / MxCAD Conversion Program)

Compiled from the actual installation package layout and startup scripts.

I. Program Location (Fixed Temp Path)

Two kinds of packages: standalone conversion program (MxConvert, mxcadassembly only) and backend service (MxServiceCode, contains BOTH the backend service and the conversion program — the complete superset). Download URLs: follow the "Link List" in the Entry Guide (take the row matching the need + platform; the Linux package is built for Ubuntu 20.04 x86_64).

Fixed temp path (download once, reuse across sessions; after the system cleans the temp dir, just re-download):

• Windows: %TEMP%\MxCAD\ (%TEMP% is the user's Temp directory environment variable; use it as-is in commands, no manual expansion needed)
• Linux: /tmp/MxCAD/

Follow the check steps in the Entry Guide: first determine what the task needs, then inspect what is in the temp path — nothing there → download the matching zip per need (conversion program only → standalone MxConvert package; backend service needed → MxServiceCode package, which includes the conversion program) and extract it to the temp path; conversion program only present → if only the conversion program is needed, run "III. Trial Version Expiry Check" first and it is ready to use; if the backend is needed, clear and re-download the backend package; backend package already extracted → run the expiry check + integrity verification, and if incomplete, clear and re-download. The temp path MUST be cleared before any re-download (each package has a fixed structure; the backend package is the complete superset). Do not scan other directories on the user's machine.

After extraction (Windows: a single top-level dir MxServiceCode_TryVersion\, same name as the zip)

MxServiceCode_TryVersion\    ← Top-level dir after extraction (same name as the zip)
├── MxServiceCode\
│   ├── NODE.JS后台程序开发.doc   ← Official backend development tutorial (not an API doc)
│   ├── MxServiceCode.sln        ← Solution file
│   └── MxServiceCode\           ← Project directory (the commands below run here)
│       ├── bin\node.exe          ← Built-in Node runtime
│       ├── mxapp.js              ← Entry point (command line)
│       ├── src\                  ← TS sources (mxcad\ = API classes, sample\ = examples, MxCommand.ts = command registration)
│       ├── Mx2DNode.node         ← Native module
│       ├── package.json          ← npm run build for compilation
│       ├── test.bat              ← Test script
│       ├── empty_template.dwg    ← Blank template
│       ├── A3.dwg / BT.DWG       ← Title block frame / title block sample blocks
│       └── t1.dwg / tree.dwg     ← Test drawings
└── MxCAD\
    └── Release\                 ← Format conversion program directory (mxcadassembly.exe + runtime dependency dlls + mxcad_ini.json, mxcode.bin, mxiconv.data + **fonts\** + files\)

After extraction (Linux: a single top-level dir MxServiceCode_TryVersion\, same name as the zip)

MxServiceCode_TryVersion\    ← Top-level dir after extraction (same name as the zip)
├── MxServiceCode\
│   ├── NODE.JS后台程序开发.doc   ← Official backend development tutorial
│   └── MxServiceCode\           ← Project directory (no .sln; the built-in runtime is `node`, not bin\node.exe;
│                                 also contains start_demo_MxServiceCode.sh, start_demo_systemlib_MxServiceCode.sh, Linux启动说明.txt)
└── Linux\
    └── MxCAD\                   ← Format conversion program directory (mxcadassembly + runtime dependencies mx/so + mxcad_ini.json, mxcode.bin, mxiconv.data + **fonts\** + files\)

Conversion program directory = MxServiceCode_TryVersion\MxCAD\Release\ under the Windows temp path, MxServiceCode_TryVersion\Linux\MxCAD\ under the Linux temp path (or MxConvert_TryVersion\ itself for the standalone MxConvert package); fonts needed for frontend drawing preview = the fonts\ directory inside it (just copy it).

II. Running MxServiceCode Commands (no service to start)

Command mode is a standalone process; call the built-in node directly:

Windows (in the project directory):

bin\node.exe mxapp.js getcaddata file=t1.dwg outfile=t1.dwg.json

Linux (in the project directory):

./node mxapp.js getcaddata file=t1.dwg outfile=t1.dwg.json linux=1

Running node mxapp.js with no arguments prints version info and the log path.

⚠️ Built-in Node version limitation (tested): bin\node.exe is v10.9.0 and supports CommonJS only — ESM (import syntax / .mjs) throws SyntaxError directly; there is no fetch, no optional chaining, or other newer features. Helper scripts written for the built-in node must use CommonJS (require) + .js; when you need ESM, use the system Node.

Linux First Deployment (permission setup)

chmod 777 start_demo_MxServiceCode.sh
./start_demo_MxServiceCode.sh     # the script already chmods mxcadassembly, mx/so, Mx2DNode.node, node

If it fails, use ./start_demo_systemlib_MxServiceCode.sh instead (uses the native libraries in the systemLib directory).

III. Format Conversion Program mxcadassembly (standalone invocation)

Windows (in the conversion program directory; the two forms are equivalent — pick by shell):

• cmd / PowerShell (bare JSON, the official-docs form, no encoding needed):

mxcadassembly.exe {"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}

• Git Bash (percent-encoded string in quotes; bare JSON returns read file error in this shell, tested):

mxcadassembly.exe "[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]"

Linux (in the conversion program directory; bare JSON in single quotes):

chmod -R 777 mxcadassembly ./mx/so/*
./mxcadassembly '{"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}'

(Equivalent alternative: ./mxcadassembly '[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]')

Parameter form convention: the program accepts two equivalent forms — ① bare JSON (the official-docs form; works directly in cmd / PowerShell / Linux bash; in bash wrap it in single quotes); ② percent-hex-encoded string wrapped in square brackets (e.g. {"a":1} → [%7B%22a%22%3A1%7D]; used internally by MxServiceCode; required in Git Bash). MxUtility.callMxCadAssembly inside MxServiceCode already encapsulates this logic — in secondary development, prefer calling through the TS API; do not hand-build the command.

⚠️ Common pitfalls (tested)

• The encoding MUST include the % prefix; plain hex (e.g. 7b2261223a317d) returns {"code":1,"message":"read file error"}
• In cmd.exe / batch files, % is a batch-variable reference: a percent-encoded string gets mangled by expansion (returns {"code":1,"message":"read file error"}) — use the bare-JSON form in cmd
• On Windows, python may be a Store placeholder program (silently no output); use the built-in bin\node.exe for temp scripts that generate encoded parameters
• When the convert command is unusable (wgh deprecated; see "MxServiceCodeCommandReference.md" detailed 1), this standalone invocation is the only way to do DWG→mxweb; the mxcad frontend only accepts mxweb

Trial Version Expiry Check

The conversion program is a trial version, valid for 6 months. If the conversion program is already in the temp path, you MUST run a test conversion before use (command-line mode, no GUI; run in the conversion program directory, using a bundled test drawing such as 1.dwg, with the output directory created first):

Windows (cmd / PowerShell): mxcadassembly.exe {"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}; Windows (Git Bash): mxcadassembly.exe "[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]"; Linux: ./mxcadassembly '{"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}'

• Returns {"code":0,"message":"ok"} → valid and usable; use it directly.
• Returns non-zero → read the version string in %TEMP%\MxNode\mxcad_*.log (recorded on every run; tested sample format: MxCAD TryVersion:7.0(2026-10-21 11:16)(64bit)(cooperate)):
  • The date in parentheses (e.g. 2026-10-21) = the trial start date; current date − trial start date > 5 months → expired; re-download the zip and extract over the temp path (URL in the Entry Guide "Link List")
  • Not expired → program environment problem; debug according to the log

Common JSON parameters (see the official "Drawing Conversion Details" for the full list):

• Convert: {"srcpath":"a.dwg","outname":"a.mxweb","outpath":"./out"} (paths relative to the conversion program directory; the outname extension decides the target format; mxweb→dwg must explicitly carry .dwg/.dxf; the outpath directory must pre-exist)
• Crop DWG: {"cmd":"cut_dwg","bd_pt1_x":0,"bd_pt1_y":0,"bd_pt2_x":100,"bd_pt2_y":100,"srcpath":"a.dwg","outname":"cut.dwg"}
• Output PDF: {"srcpath":"a.dwg","outname":"a.pdf","outpath":"./out","ret_page_extents":true,"width":"2000","height":"2000","colorPolicy":"mono"} — no cmd field (including it returns {"code":201}); output location follows the same rules as other conversions: the output directory is outpath (falls back to the conversion program directory when omitted), the file name is outname (when outname is an absolute path, write directly to that location)
• srcpath/outpath/outname all support absolute paths (including Chinese paths)
• ⚠️ The cmd parameter domain (such as print_to_pdf) belongs to the MxServiceCode backend service interface; for direct mxcadassembly.exe calls only the parameters above are valid

IV. Secondary Development Workflow

1. Modify src/sample/*.ts or add a new file (API in "Mx2DNodeSecondaryDevAPIReference.md")
2. Register the command in src/MxCommand.ts (see "MxServiceCodeCommandReference.md" section 6)
3. Compile: npm run build (node_modules is bundled; if missing, use bin\node.exe node_modules\typescript\bin\tsc --build)
4. Verify with bin\node.exe mxapp.js <command> param=value debug=1

V. Logs

• Path: %TEMP%\MxNode (same convention on Linux)
• Each command ends by printing logs end; with debug=1 the log is more detailed
• When the return is {"code":-4,"message":"js program exception, see log for details"}, check the log file

VI. Bundled Resources

File	Purpose
empty_template.dwg	Blank template; Mx2DDraw.getEmptyTemplateDwgFilePath() points to it
A3.dwg / BT.DWG	Title block frame / title block samples (the BT block contains attribute definitions); used by testParamDrawTk
t1.dwg / tree.dwg	Test drawing / test block (the tree block is used by testParamDraw)
mxcad_ini.json (in the conversion program directory)	Conversion program config (font paths, etc.); do not modify casually
fonts\	Font directory (SHX/TTF font dependencies of DWGs)