Using the Chromium Debugger
Finsemble runs on top of the OpenFin operating layer, which is a Chromium container system. Chromium contains the same debugging tools that you are used to in Chrome. The easiest way to debug is to right-click on a component and choose "Inspect Element." This will pop up Chromium's debug tools in a new window. You can also hit CTRL+ALT+D on any window to open the debugger.
An alternative debugging method is to open a Chrome browser and navigate to http://localhost:9090. Each window in your application is listed on that page. Click on the window you wish to debug and a Chromium debugger will be launched for that window. There are some limitations (e.g., you can't evaluate code in the console in a remote session), but it largely acts as you would expect.
When you open your component code in the debugger, you will see that it has been wrapped in a containing function. Finsemble uses Webpack as part of its build process. This provides automatic isolation of modules, automatic building of React modules, etc. 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 instance, if you are using a framework other than React). For more about the build process, see the Finsemble Build Process.
It isn't necessary to completely quit the application between program iterations. The dev runner automatically watches for code changes and repackages on the fly. Once you make a change and save your code, you should see the dev runner compile the changes. To access those changes, simply reload the component you've worked on. This can be done by right-clicking in the component and choosing "Reload." You can also enter CTRL+ALT+R to reload the window that you're focused on.
Resetting Your Application To Scratch
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. By default, workspaces are stored in Chromium's
localStorage. To delete
localStorage, you can run
localStorage.clear() in the console. If you prefer a more surgical approach, you can follow the steps below:
- While your app is running, open a debugger.
- Choose the "Resources" tab and then open "Local Storage"->"http://localhost" in the left nav.
- Delete any
localStorageentries that begin with "Finsemble_". This will include
Finsemble_linker. You can delete these by highlighting the entry and then pressing the "X" in the debugger's footer.
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.
For super fast clearing of
localStorage.clear()from the debugger console. Be careful though, because this will clear everything, including
localStoragefor other Finsemble or OpenFin apps on your computer.
Updating The Finsemble Framework
If you're encountering any bugs, please first check to make certain you're using the latest version of Finsemble. You can check package.json in ./node_modules/@chartiq/finsemble/package.json. To update the underlying Finsemble framework, run the following commands from your local repository directory:
npm update @chartiq/finsemble
To update the CLI:
npm update -g @chartiq/finsemble-cli
Note: Due to a bug with Gulp 4.0, npm update will not update Gulp correctly. If you need to update the entire package you will need to follow this procedure:
rmdir /S node_modules npm cache clean npm install npm install -g @chartiq/finsemble-cli
Restarting Your Application
A convenient way to restart your application without having to restart npm is to right-click on any window and then choose "Reload app and restart children."
Killing The Runtime
Problem: "npm run dev" does nothing. It just hangs.
If you find that your Finsemble application cannot run, it may be because you have zombie OpenFin 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 "OpenFin" processes that are running. You should then be able to start the dev runner again.
Deleting Your Cache
You can delete the OpenFin cache to reset the state of your application.
- Navigate to: C:\Users\
- Delete the cache folder
Please note that this will also delete the
localStorage for all of your Finsemble applications!
Debugging Inside The Finsemble Library
The Finsemble Library (FSBL.js) is automatically injected into Chromium using OpenFin's "preview" capability. This conveniently allows you to 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 always manually include FSBL.js with a script tag.
To inspect the toolbar component, press SHIFT+CTRL+D and left-click.
Hitting CTRL+C on your npm run process kills the application immediately. It's possible that Finsemble may not have had time to save recent workspace changes. In general, choosing Quit in the toolbar will avoid state issues.
If you are using Windows 8.1, make sure you disable the Gulp watchers. Due to some idiosyncrasy in node or Gulp, the watchers break the entire process. We recommend that you upgrade to Windows 10 if feasible. The watchers really increase developer productivity.
If field support is needed with debugging, see the tutorial at Capturing Log Data.
The Central Logger is a great tool for diagnosing problems across multiple windows. Check out the Central Logger tutorial.