Mobile development kit allows you to develop complex apps with a visual tool so that you can focus on business logic instead of writing code. For business logic that's too complex or specific to express with the platform's built-in actions, you can use rules. Rules let you define custom logic with flexible blocks, which are later converted to JavaScript code. If you're so inclined, you can also write the JS code directly. But did you know that you can set breakpoints in your rules to debug them at runtime? This capability allows you to augment the rapid development capabilities of the MDK editor and understand your app's behavior in fine detail. Read on to find out how it's done!
Rule debugging is accomplished with the mobile development kit client SDK, combined with the Visual Studio Code IDE (VS Code for short). You can install VS Code from this link. The MDK client SDK should also be installed along with its prerequisites. To confirm that it's working, first make sure you can build and run an MDK client project. If you’re new to MDK, take a look at the Learning Map here for introductory info, blogs, videos, and tutorials to help you get started.
You can open VS Code as you would any Mac app: by using Finder or Spotlight. However, if you open it in one of these ways, you might run into this error when you try to debug:
Actually, even if you set the nativescript.tnsPath configuration as it suggests, the debugger still may not work if it can't find your Node installation. The fix is to open VS Code from command line so that it's able to find both NativeScript and Node. Follow the quick steps in the "Launching from the Command Line" section on this help page. Then you can use the following command to open any file or directory in the IDE:
Once you've started VS Code with Terminal, you can open things with either the above command or with the usual File->Open menu.
To debug the MDK client, you must first open the client project. When you open the project, the Explorer view should look similar to this:
To debug the client, first select the Extensions view and search for and install the NativeScript extension. Click Reload to restart VS Code and enable the NativeScript extension.
In the client project, click on the Debug view, then click on the settings icon at the top. You should be able to select NativeScript here. Selecting this will populate the dropdown with a few options. Make sure that "Launch on iOS" is selected. If a launch.json file is shown, it can be closed.
First, start the iOS Simulator and select the device type you'd like to debug using the Hardware->Device menu. Then click the green arrow in the Debug view to launch the client. You may be prompted for a team ID to use for code signing. The team doesn't matter for debugging on the Simulator, but select one of the options so that the build can continue. Make sure that you can see the Debug Console by selecting View->Debug Console. Any errors will appear there. Also, in the Debug view, you'll see options to pause, stop or restart the debugging session.
Now that the app is running with VS Code attached, you can start debugging. The steps are slightly different, depending on whether you want to debug a bundle that's built into the client or one that's obtained via App Update. Either way, you'll be setting breakpoints in a webpack bundle file that includes all the definitions for your app, including any JavaScript.
First, make sure you are including a bundle file in the client. It will be located in your client project at app/bundle.js. In demo mode, app/demo.js is used instead. So you'll want to follow the steps below, replacing bundle.js with demo.js.
If you don't have any metadata to use locally, you can solve this by going to WebIDE and deploying your project. When you do so, make sure to select the download option to save the bundle.js file locally. Then move the file to the client project app directory. Open the file in VS Code.
Scroll down about 60 lines. You'll see that the lines start looking like this:
What's happening here is the definition paths were converted to a variable name and mapped to the JSON or JavaScript code they represent. You're interested in debugging a rule, so search for "_rules", with Cmd+F. Then find the line that corresponds with the rule you're looking for. For example, if I'm interested in the AssetsCount.js rule, I'll find this line:
Next, note the number at the end and search for it in the file. This is most effective if you search with the following format, since it's expected to be inside of a comment:
This search will bring you to the source code that is executed at runtime. Set a breakpoint at the beginning of the rule by clicking to the left of the line number.
After your breakpoint is set, go to the part of the application where the rule is expected to be run. You should see the breakpoint get hit. When this happens, you can view the state of the application in the Debug view. You can also use the Debug Console to print out any variables or even change the runtime state.
More debugging tips can be found in the the official VS Code debugging documentation.
If you notice an issue with your rule code, you can modify the rule in bundle.js directly. Just make sure to copy any changes you make in this way back into your metadata!
It's also possible to debug rules in a bundle that's downloaded by the client dynamically via the App Update service. The difference is that you can't open such bundle files directly in VS Code. Instead, you can set a “debugger” statement in your rule using the Code Editor. The debugger will respect these statements by treating them just like a breakpoint.
There’s also a workaround for debugging rules from App Update without adding debugger statements. The trick is to set a breakpoint just before the client invokes a rule and step into the code from there. Open app/rules/Rule.ts. Set a breakpoint where the "ruleFunction" is invoked:
Run your application until a rule is invoked, causing this breakpoint to be hit. Next, select Debug->Step Into, followed by Step Out, followed by Step Into once more. At this point, you'll be looking at the bundle.js file obtained from App Update. Set a breakpoint anywhere and it should work as expected from that point forward. You'll probably want to get rid of the breakpoint in Rule.ts. You have to repeat this process every time the app is restarted.
If you start the app in the Simulator without launching it in VS Code, or if you launch it through Xcode, you can still attach the VS Code debugger. Follow the steps in the “Launch your application in the iOS Simulator” section, but select “Attach on iOS” instead of “Launch on iOS.” This makes it possible to debug with both VS Code and Xcode at the same time.
When you launch your application from VS Code, the NativeScript CLI goes into “watch” mode. This means that any changes to bundle.js will cause the application to be restarted. At times the VS Code debugger and the iOS simulator can get out of sync. Here are a few ways to detect and resolve.
VS Code is a great tool for inspecting and debugging your MDK development environment. You usually won't need it because WebIDE allows you to define rich functionality without dealing with code at all. But in those times when you need a little more insight, you can always debug the app to see exactly what's going on. Feel free to share your thoughts and experiences in the comments!
For more information about the VS Code user interface, click here.
Prerequisites
Rule debugging is accomplished with the mobile development kit client SDK, combined with the Visual Studio Code IDE (VS Code for short). You can install VS Code from this link. The MDK client SDK should also be installed along with its prerequisites. To confirm that it's working, first make sure you can build and run an MDK client project. If you’re new to MDK, take a look at the Learning Map here for introductory info, blogs, videos, and tutorials to help you get started.
Open the MDK client project in Visual Studio Code
You can open VS Code as you would any Mac app: by using Finder or Spotlight. However, if you open it in one of these ways, you might run into this error when you try to debug:
[NSDebugAdapter] NativeScript CLI not found. Use 'nativescript.tnsPath' workspace setting to explicitly set the absolute path to the NativeScript CLI.Actually, even if you set the nativescript.tnsPath configuration as it suggests, the debugger still may not work if it can't find your Node installation. The fix is to open VS Code from command line so that it's able to find both NativeScript and Node. Follow the quick steps in the "Launching from the Command Line" section on this help page. Then you can use the following command to open any file or directory in the IDE:
code /path/to/FileOrDirectoryOnce you've started VS Code with Terminal, you can open things with either the above command or with the usual File->Open menu.
To debug the MDK client, you must first open the client project. When you open the project, the Explorer view should look similar to this:
Sample MDK client project in VS Code
Install and configure the NativeScript extension
To debug the client, first select the Extensions view and search for and install the NativeScript extension. Click Reload to restart VS Code and enable the NativeScript extension.
The Extensions view is used to install the NativeScript extension.
In the client project, click on the Debug view, then click on the settings icon at the top. You should be able to select NativeScript here. Selecting this will populate the dropdown with a few options. Make sure that "Launch on iOS" is selected. If a launch.json file is shown, it can be closed.
The NativeScript launch configurations can be selected in the Debug view.
Launch your application in the iOS Simulator
First, start the iOS Simulator and select the device type you'd like to debug using the Hardware->Device menu. Then click the green arrow in the Debug view to launch the client. You may be prompted for a team ID to use for code signing. The team doesn't matter for debugging on the Simulator, but select one of the options so that the build can continue. Make sure that you can see the Debug Console by selecting View->Debug Console. Any errors will appear there. Also, in the Debug view, you'll see options to pause, stop or restart the debugging session.
Use the “play” button to launch the MDK client.
Debug rules in your application
Now that the app is running with VS Code attached, you can start debugging. The steps are slightly different, depending on whether you want to debug a bundle that's built into the client or one that's obtained via App Update. Either way, you'll be setting breakpoints in a webpack bundle file that includes all the definitions for your app, including any JavaScript.
Setting breakpoints in a built-in bundle
First, make sure you are including a bundle file in the client. It will be located in your client project at app/bundle.js. In demo mode, app/demo.js is used instead. So you'll want to follow the steps below, replacing bundle.js with demo.js.
If you don't have any metadata to use locally, you can solve this by going to WebIDE and deploying your project. When you do so, make sure to select the download option to save the bundle.js file locally. Then move the file to the client project app directory. Open the file in VS Code.
Scroll down about 60 lines. You'll see that the lines start looking like this:
var application_app = __webpack_require__(1);What's happening here is the definition paths were converted to a variable name and mapped to the JSON or JavaScript code they represent. You're interested in debugging a rule, so search for "_rules", with Cmd+F. Then find the line that corresponds with the rule you're looking for. For example, if I'm interested in the AssetsCount.js rule, I'll find this line:
var rules_assetscount_js = __webpack_require__(508);Next, note the number at the end and search for it in the file. This is most effective if you search with the following format, since it's expected to be inside of a comment:
/* 508 */This search will bring you to the source code that is executed at runtime. Set a breakpoint at the beginning of the rule by clicking to the left of the line number.
Debugging with breakpoints
After your breakpoint is set, go to the part of the application where the rule is expected to be run. You should see the breakpoint get hit. When this happens, you can view the state of the application in the Debug view. You can also use the Debug Console to print out any variables or even change the runtime state.
More debugging tips can be found in the the official VS Code debugging documentation.
If you notice an issue with your rule code, you can modify the rule in bundle.js directly. Just make sure to copy any changes you make in this way back into your metadata!
Debugging a bundle from App Update
It's also possible to debug rules in a bundle that's downloaded by the client dynamically via the App Update service. The difference is that you can't open such bundle files directly in VS Code. Instead, you can set a “debugger” statement in your rule using the Code Editor. The debugger will respect these statements by treating them just like a breakpoint.
You can add debugger statements to rules in WebIDE to cause the debugger to pause on that line.
There’s also a workaround for debugging rules from App Update without adding debugger statements. The trick is to set a breakpoint just before the client invokes a rule and step into the code from there. Open app/rules/Rule.ts. Set a breakpoint where the "ruleFunction" is invoked:
return Promise.resolve(this.ruleFunction(this._context.clientAPI)).then((result) => {Run your application until a rule is invoked, causing this breakpoint to be hit. Next, select Debug->Step Into, followed by Step Out, followed by Step Into once more. At this point, you'll be looking at the bundle.js file obtained from App Update. Set a breakpoint anywhere and it should work as expected from that point forward. You'll probably want to get rid of the breakpoint in Rule.ts. You have to repeat this process every time the app is restarted.
Attach to a running application
If you start the app in the Simulator without launching it in VS Code, or if you launch it through Xcode, you can still attach the VS Code debugger. Follow the steps in the “Launch your application in the iOS Simulator” section, but select “Attach on iOS” instead of “Launch on iOS.” This makes it possible to debug with both VS Code and Xcode at the same time.
Troubleshooting
When you launch your application from VS Code, the NativeScript CLI goes into “watch” mode. This means that any changes to bundle.js will cause the application to be restarted. At times the VS Code debugger and the iOS simulator can get out of sync. Here are a few ways to detect and resolve.
- When the debugger is attached and working properly, the VS Code Status Bar changes from blue to orange, and the Debug Console displays log messages. In addition, the VS Code debug controls, shown below, are displayed towards the top.
- When the iOS Simulator does not reload changes to bundle.js, first restart the Simulator. Then press the 'Stop' button VS Code debug control and relaunch your application
- If launching the app seems to hang, and the VS Code debug controls are never displayed, quit and restart VS Code.
If launching fails, it may appear to hang as shown here.
VS Code is a great tool for inspecting and debugging your MDK development environment. You usually won't need it because WebIDE allows you to define rich functionality without dealing with code at all. But in those times when you need a little more insight, you can always debug the app to see exactly what's going on. Feel free to share your thoughts and experiences in the comments!
For more information about the VS Code user interface, click here.
- SAP Managed Tags:
6 Comments
