Legacy version 6 documentation. View current documentation.Legacy version 6 documentation. View current documentation.
This tutorial provides an overview of techniques that you can use to quickly iterate with Finsemble. If you need targeted support, check out Troubleshooting.
If you encounter any bugs, please first make certain that you're using the latest version of Finsemble. You can verify this through package.json in ../node_modules/@finsemble/finsemble-core/package.json.
To update the underlying Finsemble framework, run this commands from your local repository directory:
npm update @finsemble/finsemble-core
To update the Finsemble CLI, run this command from your local repository directory:
npm update -g @finsemble/finsemble-cli
Due to a bug with Gulp 4.0, npm update will not update Gulp correctly. If you need to update the entire package you need to follow this procedure:
rmdir /S node_modules
npm cache clean
npm install
npm install -g @finsemble/finsemble-cli
See also Upgrading Finsemble.
Finsemble runs on top of Chromium, which contains the same debugging tools that you are used to in Chrome. Here is how to access these tools:
An alternative debugging method is to open a browser and navigate to http://localhost:9090. Each window in your application is listed on that page. Click the window you want to debug and a Chromium Console will be launched for that window. There are some limitations (for example you can't evaluate code in the console in a remote session), but it largely acts as you would expect.
You can also force a component to spawn its console window along with itself by adding the appropriate prop to the component's config. More info in the config reference
Note: Only logger errors and warnings are written both to the Central Logger and Chrome Console. All the other logger functions (log, info, debug, verbose) are not captured by the Console.
If you built your component with the Finsemble Webpack flow, when you open your component code with a debugger, you will see that it has been wrapped in a containing function. This provides automatic isolation of modules, automatic building of React modules, and so on. For the purpose of debugging, you can simply ignore this wrapper. Place your breakpoints inside your code and it should behave as expected.
You can modify the Webpack config files, if necessary, for your own component and service code (for example, if you are using a framework other than React). For more about the build process, see the Build Process tutorial.
The Finsemble Library (FSBL.js) is automatically injected into your component's DOM. This way you can use Finsemble on any page without having to explicitly include the library. Chromium can be persnickety about debugging inside of such files (VM files). To get around this, you can manually include FSBL.js with a script tag:
<script src="/fin/FSBL.js"></script>
The Finsemble Electron Adapter log files can be found in AppData\Roaming\Electron\logs. These provide low level logging of container-level messages, which are mostly useful for debugging startup issues or issues with Finsemble's interactions with Electron. Most issues you'll encounter are more easily debugged in the Central Logger or in the javascript console for your component. However, if you think an issue is occuring at a lower-level, check the FEA log files.
Debugging a service can be difficult because the service initialization happens before the Central Logger comes online. This issue can be eliminated by configuring Finsemble to open the service’s Chromium DevTools Console when the service is launched.
In the service’s configuration, add a property visible and set it to true. This can also be done to
debug core Finsemble services (e.g., Config Service, Storage Service, etc.). The services’ configuration can be found in
../node_modules/@finsemble/finsemble-core/configs/core/services.json. You can either edit the config there or copy it
to ..configs/application/services.json.
An example of this configuration for the Storage Service:
{
"services": {
"storageService": {
"spawnAs": "window",
"name": "storageService",
"html": "$servicesRoot/storage/storage.html",
"file": "$servicesRoot/storage/storageService.js",
"category": "system",
"visible": true
}
}
}
FSBL.debug is a Boolean value. If set to true, menus will not hide on blur, and you will be able to reload the toolbar. Set the value anywhere inside of the menu or toolbar code.
To debug the storage adapter, you configure visible property for the Storage Service to true. Start Finsemble and, when the service is visible, search for the Adapter’s file name (e.g., localStorageAdapter.js). Put breakpoints in the storage adapter where you need them. To debug initialization, you may need to set breakpoints and restart Finsemble.
If breakpoints are not hit in the Storage Adapter, set breakpoints for storage adapter methods (get, save, delete,keys, clearCache and empty) in the storage service; it has corresponding methods.
The System Manager Service controls Finsemble's start-up processes. The System Manager also provides a basic but always available system log for diagnostics. Whenever there is a start-up problem, it's best to first check the system log.
The system log provides:
You can access the system log in one of three ways:
startup_app.autoShow value is set to true.finsemble.bootConfig.onErrorMakeSystemManagerVisible set to true.Depending on the case, more detailed diagnostic information can be found in the Chromium DevTools Console for the System Manager Service (see earlier in this topic).
It often isn't necessary to completely quit application components after making changes to them. The dev runner automatically watches for code changes and repackages on the fly. After you make a change and save your code, simply reload the component by right-clicking inside it and choosing "Reload." You can also press CTRL+ALT+R to reload the window that you're focused on.
As you work on your test application, the application state will be saved to the activeWorkspace. If you need to start from scratch, you can delete this workspace. To clear your storage, you can use the Storage Client:
FSBL.Clients.StorageClient.clearCache(console.log);
You can also reset your app by using the icon on the tray.
Note: Be sure to quit your application without changing the location of any windows! You want to be sure that a new
workspace isn't saved before you quit.
You can clear the browser cache for Finsemble. A separate cache folder exists for local development and each installed copy of Finsemble.
Note: This will also delete the storage for all of your Finsemble applications!
Note: AppData\Roaming\Electron\localStorage is the local storage, while "cache" is cached web pages and their assets.
AppData\Roaming<your desktop name>/e2o/ceche/remote_modules is a cache of preload files.
Hitting CTRL+C in your command prompt in which you built and ran Finsemble during development kills the application immediately. If you do this, Finsemble will not save changes to a named workspace and will try to restore the active workspace on restart.. In general, choosing Quit in the toolbar is a better option because it avoids state issues.
npm run dev does nothingIf npm run dev does nothing and the runtime is hung, it may be because you have zombie processes. This can occur, for instance, if you kill off the dev runner before the application has properly started.
To get back to a good state, open your Windows Task Manager and kill any AssimilationMain.exe, node.exe, or electron.exe processes that are running. You should then be able to start the dev runner again. You may also delete your cache (see above) to solve this issue.
If the toolbar is up, you launch the Central Logger to view the complete manifest
containing Finsemble's configuration. First, bring up the Central Logger and ensure all service and component logging is
visible by clicking on "Toggle All." Next, enter "processed manifest" into the "Filter Log" box (as opposed to the
"Filter Client List" input box). The filtered log entry includes the complete run-time manifest with Finsemble's
complete configuration under the FSBL object.
For this case, the data shown is after configuration has been fully processed on startup (e.g., macro's expanded, configuration files imported) but dynamic configuration changes haven't taken place yet. To see configuration after dynamic configuration changes, filter logs using "revised manifest" to get the revised configuration object.
In this scenario, Case 1 instructions might be useful; however that data may or may not exist depending on where start-up failed. Therefore, a third log filter, "initial manifest," is available to show the bootstrap configuration, which is the minimal initial configuration pulled from the manifest and Finsemble's core configuration in order to start the essential Finsemble services.
If neither the toolbar nor the Central Logger are available, configuration can be seen using the Chromium Console through http://localhost:9090. If the Config Service exists, its console's output can be filtered using "processed manifest." However, that data may or may not exist depending on where start-up failed.
A more reliable option is to go into the "ServiceManager" window using http://localhost:9090.
Click on the Central Logger entry and enter the command showConsole(). Filter on "initial manifest" to see the
bootstrap configuration.
For all cases above, the Central Logger's log should also be inspected for configuration-related error messages (by turning off filtering and enabling only error messages).
Follow these steps if you want to observe the registration process:
Set up the breakpoints.
routerService to open Developer Tools.Run your app and examine the checkpoints.
Launch your native app. It will hit the breakpoint for "initialHandshake".
Examine the message. It should look similar to this:
{
"header": {
"origin": "RouterClient.Finsemble WPF Demo-85-9739-Finsemble-Sales-Demo-Local",
"originIncomingTransportInfo": {
"client": "RouterClient.Finsemble WPF Demo-85-9739-Finsemble-Sales-Demo-Local"
"transportID": "FinsembleTransport",
},
"type": "initialHandshake"
}
}
Remove the breakpoint. Otherwise "initialHandshake" will continue to be sent until there is a response.
Continue running the code, and you should hit the "Finsemble.Assimilation.register" breakpoint.
Examine the message. It should look similar to this:
{
"data": {
"windowHandle": "300920",
"windowName": "Finsemble WPF Demo-85-9739-Finsemble-Sales-Demo-Local"
},
"header": {
"channel": "Finsemble.Assimilation.register",
"incomingTransportInfo": {
"transportID": "SharedWorker",
"port": 1
},
"lastClient": "RouterClient.assimilationService"
"origin": "RouterClient.Finsemble WPF Demo-85-9739-Finsemble-Sales-Demo-Local",
"originIncomingTransportInfo": {
"client": "RouterClient.Finsemble WPF Demo-85-9739-Finsemble-Sales-Demo-Local",
"transportID": "FinsembleTransport"
},
"type": "transmit"
},
}
Note: For windowless components, the windowHandle is null.
registerWindow. You should see these messages for each native app you launch:Note: Windowless components don’t generate these messages because they don’t have a window to register. If you search for the name of your component, you should see messages similar to:
11:37:37:470 COMPONENT LIFECYCLE: STATE CHANGE: created DotNetWindowless-26-4964-Finsemble-Seed-Local windowService
11:37:37:630 COMPONENT LIFECYCLE: STATE CHANGE: ready DotNetWindowless-26-4964-Finsemble-Seed-Local windowService
You might sometimes want to add breakpoints to your code as you’re debugging it, so that you can collect more details at a specific point. You can do this in VS Code by adding this launch.json to your .vscode file. Here is the code:
{
"version": "0.2.0",
"configurations": [
{
"name": "Node Server",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/server/server.js"
},
{
"name": "Electron Main",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/node_modules/@chartiq/finsemble-electron-adapter/startup/devIndex.js",
"stopOnEntry": false,
"args": ["ELECTRON_DEV=true"],
"cwd": "${workspaceRoot}/node_modules/@chartiq/finsemble-electron-adapter",
"runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron",
"runtimeArgs": [
"--remote-debugging-port=9090 --inspect=5858",
"--manifest http://localhost:3375/configs/openfin/manifest-local.json"
],
"env": {}
},
], "compounds": [
{
"name": "Node Server + Electron Main",
"configurations": ["Node Server", "Electron Main"]
}
]
}
Here are the steps:
'configurations' objects and adding the 'compounds' property from the attached launch.json).To zero in on a specific problem, see the Troubleshooting tutorial.
Check out the Central Logger, a great tool for diagnosing problems across multiple windows.