Data Reference Finder Configuration Guide

To use the Data Reference Finder effectively, you need to create a configuration file that specifies where your data is stored and how to parse it.
Currently, only XML data parsing is supported. The configuration file should be written in JSON format.

---

Location

The configuration file is located in a folder named DataReferenceFinder which is placed next to your Visual Studio Solution file.
The name of the configuration file is DataReferenceFinderConfig.json

---

Configuration Structure

1. DataProjectBasePath

A string that defines the base path of your data project. If you define this you can make the paths of our DataLocationEntries relative to this.
This path can either be relative (to your solution file) or absolute.

2. DataLocationEntries

This section defines a list of locations where your project’s data is stored.
Paths can be either relative (to your DataProjectBasePath or if not defined your solution file) or absolute.

Properties:

• Name: A unique name to identify the data location entry.
• Path: The file path to your data files (can be relative to your solution or absolute).
• ExtensionFilters: A list of file extensions that represent relevant data files.
  (Leaving this empty will include all files, but remember, only XML files are parsed.)
• UsedParsingDescriptions: A list of parsing descriptions (defined later) that apply to files in this location.

3. DataParsingDescriptions

Parsing descriptions are key to getting the full benefit of the Data Reference Finder. They specify how to extract and interpret data from your XML files, converting it into a generic Data Entry format used internally by the extension.

• XPath expressions are used to extract the relevant data from XML files.

Properties:

• Name: The name of the parsing description, referenced by UsedParsingDescriptions in DataLocationEntries.
• TypeName: The type of data found with this parsing description.
  (If not provided, the Name of the description is used as the type.)
• BaseExpression: XPath expression that returns an XML node for each data entry in a file.
  All other XPath expressions are evaluated from this node to extract additional data.
• EntryIdentifierExpression: XPath expression to extract the unique identifier (GUID or string) of each data entry.
  (To combine multiple strings into one identifier, use the pipe | symbol.)
• ReferencedIdentifierExpressions: A list of XPath expressions to extract identifiers of other entries referenced by this entry.
  (Filling this out allows the extension to find and manage references between data entries.)
• ParentIdentifierExpression: XPath expression to extract the identifier of the parent entry, if applicable.
  (This is optional, but including it enables the extension to display full hierarchical paths to your data entries.)
• SubTypeExpression: XPath expression to extract a subtype for the data entry.
  (While all entries will have the same base type, subtypes help differentiate specific entries. This is optional.)

4. GuidFieldIdentifiers

A list of string values that indicate potential GUID fields in your code files.

If one of these strings is found in a word in a code file, the word is recognized as a possible GUID. The code file is then searched for other occurrences of this word to check if a GUID is on the same line. If this is the case, the word is interpreted as that GUID.

5. DataEditorServerUri

A string that defines the URI used to connect to your Data Editor via WebSocket, allowing you to send commands to the Data Editor.
(For more information, see the upcoming documentation on Data Editor connections.)

---

Example Configuration

{
  "DataProjectBasePath": "../../DataReferenceFinder_ExampleData/",
  "DataLocationEntries": [
    {
      "Name": "Relative Data Location",
      "Path": "MyDataFolder/MyDataSubFolder",
      "ExtensionFilters": [".xml"],
      "UsedParsingDescriptions": ["SimpleParsingDescription", "AdvancedParsingDescription"]
    },
    {
      "Name": "Absolute Data Location",
      "Path": "D:/MyProjectFolder/MyDataFolder",
      "ExtensionFilters": [".xml"],
      "UsedParsingDescriptions": ["CombinedIdentifierParsingDescription", "RefCombinedIdentifierParsingDescription"]
    }
  ],
  "DataParsingDescriptions": [
    {
      "Name": "SimpleParsingDescription",
      "BaseExpression": "//xmlAttribute[name and guid]",
      "EntryIdentifierExpression": "./guid/@value",
      "ReferencedIdentifierExpressions": [],
      "NameExpression": "./name/@value",
      "ParentNameExpression": "name(..)",
      "SubTypeExpression": "name(../..)"
    },
    {
      "Name": "AdvancedParsingDescription",
      "TypeName": "AdvancedData",
      "BaseExpression": "//*[guid and name and (subType or type)]",
      "EntryIdentifierExpression": "./guid",
      "ReferencedIdentifierExpressions": [
        "./@reference_guid",
        "./@link_guid",
        "./@domain_guid"
      ],
      "NameExpression": "./name",
      "ParentIdentifierExpression": "./@parent_guid",
      "SubTypeExpression": "./subType | ./type"
    },
    {
      "Name": "CombinedIdentifierParsingDescription",
      "BaseExpression": "//*[name and id]",
      "EntryIdentifierExpression": "./name/@value | ./id/@value",
      "ReferencedIdentifierExpressions": [],
      "NameExpression": "./name/@value",
      "ParentNameExpression": "name(..)",
      "SubTypeExpression": "name(..)"
    },
    {
      "Name": "RefCombinedIdentifierParsingDescription",
      "BaseExpression": "//myAttribute[name]",
      "EntryIdentifierExpression": "./@name",
      "ReferencedIdentifierExpressions": [
        "./name/@value | ./id/@value"
      ],
      "NameExpression": "./name/@value",
      "ParentNameExpression": "name(..)",
      "SubTypeExpression": "name(..)"
    }
  ],
  "GuidFieldIdentifiers": [
    "_guid"
  ],
  "DataEditorServerUri": "ws://localhost:9000"
}