AppProfileSafe - Support Portal

What Is a Mapping File?

This page explains in detail how AppProfileSafe applies mapping rules during import. Understanding the application order, pattern types, and path normalization ensures your rules produce the correct results.


Path Transformation Pipeline

Registry and file paths go through different transformation pipelines during import:

Registry Paths
  1. Read the raw path from the registry export XML
  2. Normalize the hive prefix to the long form (e.g. HKCU\ → HKEY_CURRENT_USER\)
  3. Apply registry mapping rules sequentially
  4. Write to the Windows registry at the mapped path

Important: Mapping rules always receive the normalized (long-form) path. If you write a rule that matches HKCU\, it will never match because the path has already been expanded to HKEY_CURRENT_USER\ before mappings are applied.

File Paths
  1. Read the OriginPath from the manifest (e.g. %APPDATA%\Mozilla\Firefox)
  2. Expand environment variables (e.g. → C:\Users\CurrentUser\AppData\Roaming\Mozilla\Firefox)
  3. Apply file mapping rules sequentially
  4. Copy the file to the mapped target path

Important: File mapping rules receive the expanded path with environment variables already resolved. Rules should match actual paths, not %APPDATA% placeholders.


Sequential Application

Rules are applied one after another, from top to bottom. The output of one rule becomes the input for the next. This means:

  • The order matters — reordering rules can produce different results
  • A rule can match text that was inserted by a previous rule
  • Only enabled rules are applied (disabled rules are skipped)
  • Rules with an empty or whitespace-only pattern are skipped
Example

Given the input path C:\Users\Alice\AppData and these rules:

# Pattern Replacement Result After Rule
1 Alice Bob C:\Users\Bob\AppData
2 C:\Users D:\Profiles D:\Profiles\Bob\AppData

If the rules were in reverse order, rule 2 would run first on the original input and produce D:\Profiles\Alice\AppData, then rule 1 would replace Alice with Bob.


String vs. Regex Mode

String Mode (Default)

When the rule type is String, the pattern is treated as a literal string. AppProfileSafe automatically escapes all special regex characters (like \, ., *) before matching. This is the safest option for simple find/replace operations, especially with Windows paths that contain backslashes.

Example: A pattern of C:\Users\Alice matches exactly that text — the backslashes are not interpreted as regex escape characters.

Regex Mode

When the rule type is Regex, the pattern is used as a full .NET regular expression. This gives you powerful matching capabilities but requires careful escaping. Use \\ for literal backslashes in regex patterns.

Example: A pattern of HKEY_USERS\\S-1-5-21-\d+-\d+-\d+-\d+ matches any user SID in the registry path.

If a regex pattern is invalid, the rule is silently skipped and the next rule is applied.

Feature String Regex
Backslash handling Literal — no escaping needed Must use \\ for literal backslash
Wildcards Not supported .*, \d+, [a-z]+, etc.
Capture groups Not supported (group) → $1 in replacement
Case sensitivity Case-sensitive (default regex behavior) Use (?i) inline flag for case-insensitive matching
Error on invalid pattern Cannot happen (auto-escaped) Rule is silently skipped


Environment Variables in Replacements

The replacement string supports Windows environment variables in %VAR% format. These are expanded when the rule is applied — not when the mapping file is loaded. This means the same mapping file can work on different machines.

Example rule:

Pattern Replacement
C:\Users\OldUser C:\Users\%USERNAME%

On a machine where the current user is "NewUser", %USERNAME% expands to NewUser, producing C:\Users\NewUser.

If an environment variable is not defined on the system, it is left unexpanded (e.g. %UNKNOWN% remains as-is).


Registry Path Normalization

Before mapping rules are applied, registry paths are normalized to the long-form hive name:

Short Form Normalized Form
HKCU\ HKEY_CURRENT_USER\
HKLM\ HKEY_LOCAL_MACHINE\
HKCR\ HKEY_CLASSES_ROOT\
HKU\ HKEY_USERS\
HKCC\ HKEY_CURRENT_CONFIG\

Always write registry mapping patterns using the long form to ensure they match.


Matching Behavior

Both String and Regex rules use .NET's Regex.Replace internally. This means:

  • All occurrences of the pattern are replaced (not just the first one)
  • Matching is case-sensitive by default. For case-insensitive matching in Regex mode, add (?i) at the beginning of the pattern.
  • The replacement string can use $1, $2, etc. to reference capture groups in Regex mode


Best Practices

  • Use String mode for simple user name or path replacements
  • Use Regex mode only when you need wildcards, capture groups, or pattern matching (e.g. SID replacement)
  • Be specific with patterns — a pattern of User would also match UserData or Users
  • Always simulate after creating or modifying mapping rules — see Running a Simulation
  • Order rules from most specific to least specific to avoid unintended cascading replacements
  • Use environment variables in replacements to make mapping files portable across machines


See Also