C3 AI VS Code ExtensionThis is the official VS Code extension for development on the C3 AI Platform. The extension enhances the application development experience on the C3 AI Platform by providing C3 Type System-specific aid across type files and implementation files. These include code completion, in-text documentation, testing and debugging capabilities, and other developing utilities. For more information on C3 AI, visit our website.
PrerequisitesBefore developing an application on the C3 AI Platform, you must:
Setup the local workspaceA local workspace is a folder or directory on the local file system of your client device. This is where you can store your C3 AI application package code. Ensure that you have a workspace (a directory) that contains your packages like the following example:
Install the extensionIn VS Code, select the Extensions tab on the Activity Bar and search for C3 AI. It is best practice to have the latest version of the extension. If the server version is incompatible with the newest version of the extension, you can install an older version of the extension on this page. Set up the developers environmentCreate an environmentFor application development, connect to a Single Node Environment. Once connected to a single node environment, you will be able to start applications based on the packages in your workspace. Use C3 AI Studio to create environments. Refer to the example below for creating a single node environment in Studio:
Connect and synchronize the workspaceOnce the extension is installed, a pop-up welcome page launches allowing you to select or confirm your workspace and enter your environment URL. To manually access the welcome page, go to the C3: EXPLORER panel and choose one of the following options:
On the welcome page, you can confirm your workspace and connect to the environment URL. Workspace: Select the folder that contains the packages you want to begin development on. Environment URL: Enter the Environment URL that you have created in the previous section. The URL can be obtained from C3 AI Studio by going to the desired environment and selecting Open in VS Code from the ellipsis menu.
Upon successful connection and sync, you should see the following message in the notification box as well as within the output tab. Additionally, you will also see the package explorer in the C3 AI tab populate with your local and external (dependency) packages.
Advanced Settings
On the welcome page, there are options for advanced settings:
Note about the Union setting:
Scenario 1:
Scenario 2:
Scenario 3:
Scenario 4:
Adjust reconnect attemptsIf you happen to lose your internet connection temporarily (e.g., your VPN crashes), the extension attempts to reconnect five times, with each attempt lasting for 30 seconds. When VSCE detects the loss of connection, it will provide a notification as shown below.
You can change the number of attempts:
Start applicationOnce your package is synced and validated with the server, right-click on the package and select Start App to initiate your application. A green circle next to the application name indicates that it is running. For detailed setup instructions, refer to Set up the C3 AI VS Code extension. Now you are ready to start building applications! Review validationAfter the synchronization process, the remote environment will begin to validate all the new files that it has received. During this process, you will see the icons on the files in the Package Explorer transition across a few states outlined below.
Environment health metricsUpon connection, the extension provides two health metrics for the environment: CPU and Memory. These can be found on the bottom status bar next to the environment URL.
When these values exceed certain thresholds (where the default thresholds are set to be 90% for CPU and 75% for memory), you will get a notification.
C3 AI VSCE FeaturesUpon successful connection, you should be able to test out the following features. There are 3 main areas that are useful within the C3 AI tab: The Package Explorer (1), the Tester (2), and the Panel (3) tabs (which contain C3 AI: Package Issues , C3 AI: Test Results, and Output).
Package ExplorerThe package explorer is the first (1) section highlighted above. Once you have an established connection, you should see a list of your local packages as well as any dependencies from the server (for example, the platform package). This is also the recommended interface for interacting with your packages (over the native file explorer). From here you should be able to do the following:
TesterThe tester is the second (2) section highlighted above. This is where you can queue up a list of test files to run, execute test files and view the history of the last 10 test runs. There are 2 tabs: Queue and History. Via the test queue, you can interact with a set of test files by:
You can also interact with individual test files in a similar fashion. Via the test history tab, you review the results of the last 10 test files that you’ve run. Clicking on a specific test file result will open the output tab with the detailed results. Tester SettingsThe extension allows you to run tests in two different modes.
To toggle between these options, select the settings icon in the TESTER section.
JavaScript (JS) DebuggerIn addition to running tests, users can also debug individual test files.
To start the debug session:
Once the debugging session has started, you will see a toolbar located near the top of the screen that has the icons. Restart and Disconnect icons affect the debug session while the other icons affect the line-by-line execution of the program. For more information on these icons, see Debug Actions. Go to the left side navigation, Run and Debug tab, to use the debugging functionality and view information like:
In the panel tabs, go to the Debug Console tab to inspect complex objects with nested fields and evaluate expressions using REPL (Read-Eval-Print Loop) feature. The C3 AI debugger adds custom logs with information on tests starting, passing, and failing.
(Preview Feature) Debugging server-side methods: The C3 AI debugger provides an experimental feature that allows debugging of server-side methods and executes them in Node instead of on the server. To enable this behavior, breakpoints must be set on the JavaScript implementation file. All server-side methods on the file will be debuggable. This is supported for multiple files.
Panel TabThe panel is the third (3) section highlighted in the image above. This section has multiple tabs within it that are relevant to the C3 developers. These include Output, C3 AI: Package Issues, and C3 AI: Test Results. OutputThis tab provides logging information to let users know what is happening when they are using the extension. During the initial connection and sync, it will provide insight into which stage of the process the user is in. Additionally, upon making code changes, the output tab provides instant feedback regarding the synchronization of files.
Package IssuesThis tab regularly updates with any syntax or deployment errors that your code has. This is a good one to keep open as you make changes within your application.
Test ResultsThis tab provides two views, one for the test results and the other for server logs. The first view provides the status and results of any tests that you run. If there is an error the line where the error is located is presented. The second view outputs a server log snapshot of the test run.
Developer UtilitiesThe extension provides several C3 Type specific IntelliSense features including the following:
JS NotebookThe extension also offers a JS Notebook. The notebook will automatically connect to your remote environment and will allow you to run JS console commands and Type APIs within VS Code. You will also be able to switch context to any applications that you start within your SNE. To interact with your remote environments and applications from within VS Code, open a new JS notebook by clicking on the notebook icon as shown below.
Alternatively you can also right click on a package that has a running application and select the option to "Create Notebook". Once in the notebook, you can run Type APIs to query data, set configs, and more, just as you would from the console. Below is an overview of the JS notebook header; these actions should look similar to those who are familiar with Jupyter notebooks.
The JS notebook provides an opportunity to document APIs and run them within the same notebook, making them ideal for training tutorials and implementation guides.
Remote Python DebuggerThis extension provides a feature for debugging Python code executed on a remote server. Starting the Remote Python DebuggerYou can start the Python debugger in two ways:
Once the debugger has started successfully, you will see the debug toolbar at the top of the screen. Debugging Python CodeThe debugger supports the following features:
Here are some ways to hit breakpoints in Python code: Running actions through js notebook (Recommended way): To debug server side python action through JS Notebook, you can add breakpoint in the Type implementation files and start the notebook in the your application and try running the action. The debugger will stop at the breakpoint and the file will be focused in the editor.
Running actions through the console: Similar to the notebook, you can add breakpoints in the Type's Python implementation files. Open the console of the your application and try running the action. The debugger will stop at the breakpoint in the Python action in VS Code.
Running actions through Jupyter notebook: To hit breakpoints when running actions through Jupyter notebooks, you need to ensure that the actions are being ran on the remote server. For example, if you want to run an action implemented in py-a runtime, ensure that the Jupyter notebook kernel does not have the same runtime py-a or has all the dependencies of py-a. You can do this by creating a Python runtime without any dependencies and running the action in that runtime
Limitations of Remote Python Debugger.
FeedbackWe are constantly working to improve the extension by fixing bugs and adding new features. If you have any feedback that you wish to share with the developer team, please reach out to us at https://support.c3.ai/. |