From f5b028d76bdd49230ddde2990f99249a84fd0bca Mon Sep 17 00:00:00 2001 From: Marks Troicins Date: Tue, 4 Aug 2026 11:13:13 +0200 Subject: [PATCH 1/2] Mx.exe module-import updated documentation --- .../general/mx-command-line-tool/module.md | 41 ++++++++++++++++++- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/content/en/docs/refguide/general/mx-command-line-tool/module.md b/content/en/docs/refguide/general/mx-command-line-tool/module.md index c1e3206da1b..09c8f9251cd 100644 --- a/content/en/docs/refguide/general/mx-command-line-tool/module.md +++ b/content/en/docs/refguide/general/mx-command-line-tool/module.md @@ -85,18 +85,52 @@ The `mx module-import` command imports a source module (*.mpk*) into an app. Use the following command pattern for `mx module-import`: -`mx module-import MPK_PATH MPR_PATH` +`mx module-import MPK_PATH MPR_PATH [--import-mode ] [--conflict ] [--metadata ]` For `MPK_PATH`, enter a *.mpk* file with the module you want to import. For `MPR_PATH`, enter a *.mpr* file of the project you want to import a module into. +#### --import-mode + +The `--import-mode` option controls what happens when a module with the same name already exists in the app: + +* `add` – Add the module. Fails if a module with the same name already exists. This is the default. +* `replace` – Replace the existing module. Fails with exit code 310 if no module with that name is found in the app. +* `update` – Replace the module if it already exists, or add it if it does not. + +#### --conflict + +The `--conflict` option controls what happens when a same-name module already exists, and applies to the `add` and `update` modes: + +* `fail` – Return an error. This is the default. +* `take_mine` – Keep the existing module and skip the import silently. +* `take_theirs` – Replace the existing module. + +#### --metadata + +The `--metadata` option controls how marketplace identity fields are handled when a module is replaced. This option only takes effect when a replacement actually occurs. + +* `take_new` – Use the identity fields from the incoming module. This is the default. +* `take_existing` – Copy the identity fields from the module being replaced. +* `erase` – Clear all identity fields. + +Regardless of the chosen strategy, `FromAppStore` is always inherited from the existing module, and `AppStoreVersion`/`AppStoreVersionGuid` fall back to the existing values when the incoming module does not provide them. + ### Examples -Here is an example: +Add a module to an app: `mx module-import MyNewModule.mpk MyApp.mpr` +Replace an existing module, keeping its marketplace identity: + +`mx module-import MyNewModule.mpk MyApp.mpr --import-mode replace --metadata take_existing` + +Update a module if it exists or add it if not, overwriting on collision: + +`mx module-import MyNewModule.mpk MyApp.mpr --import-mode update --conflict take_theirs` + ### Return Codes The command returns 0 if it is successful. @@ -121,6 +155,9 @@ In case of errors, the exit code consists of three digits `XYZ`: * 6 – Project can't be loaded * 7 – Module can't be loaded * 8 – Import of a module failed. Resulting project can't be saved. + * 9 – File does not exist. + * 10 – `--import-mode replace` was specified but no module with that name exists in the project. + * 11 – The MPK file has an unrecognised extension. For example: From da8d13c73ecabe06873e5a8c41be35806bb818db Mon Sep 17 00:00:00 2001 From: Marks Troicins Date: Tue, 4 Aug 2026 11:17:02 +0200 Subject: [PATCH 2/2] Avoid command headers --- .../refguide/general/mx-command-line-tool/module.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/content/en/docs/refguide/general/mx-command-line-tool/module.md b/content/en/docs/refguide/general/mx-command-line-tool/module.md index 09c8f9251cd..a8d3a93a7f9 100644 --- a/content/en/docs/refguide/general/mx-command-line-tool/module.md +++ b/content/en/docs/refguide/general/mx-command-line-tool/module.md @@ -91,25 +91,19 @@ For `MPK_PATH`, enter a *.mpk* file with the module you want to import. For `MPR_PATH`, enter a *.mpr* file of the project you want to import a module into. -#### --import-mode - -The `--import-mode` option controls what happens when a module with the same name already exists in the app: +For `--import-mode`, enter one of the following values to control what happens when a module with the same name already exists in the app: * `add` – Add the module. Fails if a module with the same name already exists. This is the default. * `replace` – Replace the existing module. Fails with exit code 310 if no module with that name is found in the app. * `update` – Replace the module if it already exists, or add it if it does not. -#### --conflict - -The `--conflict` option controls what happens when a same-name module already exists, and applies to the `add` and `update` modes: +For `--conflict`, enter one of the following values to control what happens when a same-name module already exists. This applies to the `add` and `update` modes: * `fail` – Return an error. This is the default. * `take_mine` – Keep the existing module and skip the import silently. * `take_theirs` – Replace the existing module. -#### --metadata - -The `--metadata` option controls how marketplace identity fields are handled when a module is replaced. This option only takes effect when a replacement actually occurs. +For `--metadata`, enter one of the following values to control how marketplace identity fields are handled when a module is replaced. This option only takes effect when a replacement actually occurs: * `take_new` – Use the identity fields from the incoming module. This is the default. * `take_existing` – Copy the identity fields from the module being replaced.