TrakSYS TS Code
This extension allows connection to a TrakSYS instance, extracting the script-based configuration and behaviors for editing within the VS Code environment.
TrakSYS Compatibility
This TS Code extension is designed to work against any version of TrakSYS, starting with version 14.1.0. As new versions of TrakSYS are released, it may be possible that an older version of this extension may have specific difficulties with new entities. This type of incompatibility should be handled by updating this extension to the latest version.
Setting up a New Project
Once the extension is installed, the following steps can be used to create a new TS Code project folder and connect to a TrakSYS instance...
- From the file system, create an empty folder that will be the root for the TS Code project. This folder will hold the local project and TrakSYS content that are extracted from the target TrakSYS instance as it is edited. It should be named with relation to the TrakSYS target it will connect to. A recommended naming convention could be
company-dev, or company-test, or company-prod.
- Open VS Code, and use the
File | Open Folder menu to open the new project folder.
- Use the command palette (Ctrl-Shift+P), find and execute the
TS Code: Enable TS Code for this Folder command.
- A dialog should be presented asking to create a new
tscode.toml file. This is the main settings file for a TS Code project where connection and behavior settings are managed. Proceeding will create and open the file for editing.
- Within the
tscode.toml file editor, set the following minimum settings to establish a connection...
- name
- tsurl
- [connection] server
- [connection] database
- [connection] useWindowsAuthentication
- [connection] domain
- [connection] user
- Saving this file for the first time will prompt asking to confirm establishing the initial connection. Proceeding will begin the process by prompting for the database password. Future password prompts will occur only if the connection fails or certain connection settings change. Passwords are stored in VS Code's SecretStorage API, keyed by a SHA256 fingerprint of the connection identity.
- The connection and load process may take a few minutes, progress will be reported as the tree-view loads.
When the load completes, the project can be used for interaction and editing.
Source Control
The TS Code local file structure is not intended for use with source control repositories. The operating philosophy is that the files are regularly being updated back to the target TrakSYS instance. While some modifications may remain on a specific user's local computer for some time for authoring and syntax checking, it is not designed as a source-control type system.
Main Menu
The following describes the menu options available when clicking the ... Menu from the TS Code header.
Refresh All : Pulls all tree-view content from the server. This command is useful when re-opening a TS Code project for the first time after time has passed. This refreshes the local content with the latest from the source. This will overwrite any local changes that have been made but not merged.
Update References : Pulls down all of the TrakSYS DLLs needed for syntax checking. This includes any dynamic content such as Connect plug-ins.
Build TS Web : Runs a compile and syntax check for all Shared and Web Scripts.
Build LS : Runs a compile and syntax check for all Shared and Logic Service Scripts.
Build DMS : Runs a compile and syntax check for all Shared and Data Management Service Scripts.
Reveal Active File : Locates the related tree-view node for the currently focused editor file.
Settings : Opens the tscode.toml settings file.
Target Instance Poll : TS Code continuously polls the target TrakSYS instance for changes to the relevant content/entities. The purpose is to notify a local user that the version of an entity/file that they have retrieved has now been changed on the target instance. This is communicated by changing the tree-view node to a red color.
Configurable Entities
The following sections describe the different parts of the TS Code tree-view. They are grouped by common file types and interaction patterns.
Page Definitions, Content Pages and Parts
The Page Definition, Content Pages, and Content Parts nodes allow editing the script-based components of TrakSYS user interface entities.
New Entities
New Page Definitions, Content Pages and Parts CANNOT be created from within TS Code.
Save-Back
The save-back philosophy of these entities is immediate. The reasoning is that edits to these entities are typically saved, then refreshed in the TS Web to see the results.
When a file is saved, it is immediately saved back to the target TrakSYS instance. If however, another user has edited the content in the target instance since the last local pull, then a diff viewer will be displayed. This is a simplified diff-decision experience, either the local or the database version can be selected (no line-by-line merging).
Structure
Each entity in the hierarchy contains several different sub-files (cs, css, js, shared.css, shared.js). These files can be edited independently of each other.
Dirty
There are 2 scenarios where an entity in the tree-view will be marked as dirty...
Orange : When local files are edited and saved from an external source (not from TS Code), and when the target content is different than the last known version. This typically happens when edited by an AI tool or another external process. When this occurs, the file must be manually merged by executing the Merge File command.
Red : When someone edits the content on the target instance. The TS Code poll DOES NOT check for this (its too time consuming). This is only checked for on initial project load.
Reload (and children) : Reloads the node, and all of its children, refreshing the content from the target instance.
Dev in TrakSYS : Opens this entity in TrakSYS Web.
Merge : Initiates the save-back merge for this entity/file and all of its children.
Scripts
The Scripts tree-view entities cover all the various C# script entities in TrakSYS.
New Entities
New Scripts CANNOT be created from within TS Code.
Save-Back
The save-back philosophy of these entities is deferred. Meaning that many edits and syntax checks can be done locally before saving back to the target instance. The reasoning is that breaking changes while editing could impact other users (saving back an incomplete edit, and then another user working in another area does a compile). The local use decides when to merge their changes back to the target.
Structure
Script nodes contain only a single C# cs file content node.
Dirty
There are 2 scenarios where an entity in the tree-view will be marked as dirty...
Orange : When local files are edited and saved from either TS Code or an external source (AI edits). When this occurs, the file must be manually merged by executing the Merge File command.
Red : When someone edits the content on the target instance. The TS Code poll checks for this and alerts the local user by turning the node red.
Rename : Renames the entity immediately locally, and in the target instance.
Dev in TrakSYS : Opens this entity in TrakSYS Web.
Merge : Initiates the save-back merge for this entity/file and all of its children.
Views and Stored Procedures
These tree-view nodes allow direct editing access to View and Stored Procedures in the target TrakSYS database.
New Entities
New Views and Stored Procedures can be created from within TS Code.
Save-Back
The save-back philosophy of these entities is deferred. Meaning that many edits and syntax checks can be done locally before saving back to the target instance. The reasoning is that breaking changes while editing could impact other users (saving back an incomplete edit, and breaking the live view or stored procedure for other dev users). The local use decides when to merge their changes back to the target.
Structure
View and Stored Procedure nodes contain only a single C# cs file content node.
Dirty
There are 2 scenarios where an entity in the tree-view will be marked as dirty...
Orange : When local files are edited and saved from either TS Code or an external source (AI edits). When this occurs, the file must be manually merged by executing the Merge File command.
Red : When someone edits the content on the target instance. The TS Code poll checks for this and alerts the local user by turning the node red.
New : Creates a new entity in the target instance.
Rename : Renames the entity immediately locally, and in the target instance.
Dev in TrakSYS : Opens this entity in TrakSYS Web.
Merge : Initiates the save-back merge for this entity/file and all of its children.
