Script Debugger 7 0 5 – Applescript Authoring Environment Software

1. Script Debugger 7 0 5 – Applescript Authoring Environment Software Download
2. Script Debugger 7 0 5 – Applescript Authoring Environment Software Pdf
3. Script Debugger 7 0 5 – Applescript Authoring Environment Software Downloads

We are pleased to announce the release of Script Debugger 7.0.7. Script Debugger 7.0.7 is a free maintenance release addressing a series of issues that came to light following the release of Script Debugger 7.0. In particular, this release corrects a regression where Script Debugger looks terrible on macOS Mojave in Dark Mode. The ability is primarily included so you can build Cocoa applications with AppleScript Studio, but you could use it for any AppleScript development. If you're looking for something simpler, you might check out Smile, which isn't really a debugger, but does offer features useful for debugging that aren't available in the standard Script Editor.

This topic describes how to use JavaScript to create scripts that understand debugger objects and extend and customize the capabilities of the debugger.

Overview of JavaScript Debugger Scripting

Script providers bridge a scripting language to the debugger's internal object model. The JavaScript debugger scripting provider, allows the for use of JavaScript with the debugger.

When a JavaScript is loaded via the .scriptload command, the root code of the script is executed, the names which are present in the script are bridged into the root namespace of the debugger (dx Debugger) and the script stays resident in memory until it is unloaded and all references to its objects are released. The script can provide new functions to the debugger's expression evaluator, modify the object model of the debugger, or can act as a visualizer in much the same way that a NatVis visualizer does.

This topic describes some of what you can do with JavaScript debugger scripting.

These two topics provide additional information about working with JavaScript in the debugger.

JavaScript Scripting Video

Defrag Tools #170 - Andy and Bill demonstrate JavaScript extensibility and scripting abilities in the debugger.

The Debugger JavaScript Provider

The JavaScript provider included with the debugger takes full advantage of the latest ECMAScript6 object and class enhancements. For more information, see ECMAScript 6 — New Features: Overview & Comparison.

JsProvider.dll

JsProvider.dll is the JavaScript provider that is loaded to support JavaScript Debugger Scripting.

Requirements

JavaScript Debugger Scripting is designed to work with all supported versions of Windows.

Loading the JavaScript Scripting Provider

Before using any of the .script commands, a scripting provider needs to be loaded using the .load (Load Extension DLL) command. To load the JavaScript provider, use the following command.

Use the .scriptproviders command to confirm that the JavaScript provider is loaded.

JavaScript Scripting Meta Commands

The following commands are available to work with JavaScript Debugger Scripting.

Requirements

Before using any of the .script commands, a scripting provider needs to be loaded using the .load (Load Extension DLL) command. To load the JavaScript provider, use the following command.

.scriptproviders (List Script Providers)

The .scriptproviders command will list all the script languages which are presently understood by the debugger and the extension under which they are registered.

In the example below, the JavaScript and NatVis providers are loaded.

Any file ending in '.NatVis' is understood as a NatVis script and any file ending in '.js' is understood as a JavaScript script. Either type of script can be loaded with the .scriptload command.

For more information, see .scriptproviders (List Script Providers)

.scriptload (Load Script)

The .scriptload command will load a script and execute the root code of a script and the initializeScript function. If there are any errors in the initial load and execution of the script, the errors will be displayed to console. The following command shows the successful load of TestScript.js.

Any object model manipulations made by the script will stay in place until the script is subsequently unloaded or is run again with different content.

For more information, see .scriptload (Load Script)

.scriptrun

The .scriptrun command will load a script, execute the root code of the script, the initializeScript and the invokeScript function. If there are any errors in the initial load and execution of the script, the errors will be displayed to console.

Any debugger object model manipulations made by the script will stay in place until the script is subsequently unloaded or is run again with different content.

For more information, see .scriptrun (Run Script).

.scriptunload (Unload Script)

The .scriptunload command unloads a loaded script and calls the uninitializeScript function. Use the following command syntax to unload a script

For more information, see .scriptunload (Unload Script).

.scriptlist (List Loaded Scripts)

The .scriptlist command will list any scripts which have been loaded via the .scriptload or the .scriptrun command. If the TestScript was successfully loaded using .scriptload, the .scriptlist command would display the name of the loaded script.

For more information, see .scriptlist (List Loaded Scripts).

Get Started with JavaScript Debugger Scripting

HelloWorld Example Script

This section describes how to create and execute a simple JavaScript debugger script that prints out, Hello World.

Use a text editor such as Notepad to create a text file named HelloWorld.js that contains the JavaScript code shown above.

Use the .load (Load Extension DLL) command to load the JavaScript provider.

Use the .scriptload command to load and execute the script. Because we used the function name initializeScript, the code in the function is run when the script is loaded.

After the script is loaded the additional functionality is available in the debugger. Use the dx (Display NatVis Expression) command to display Debugger.State.Scripts to see that our script is now resident.

In the next example, we will add and call a named function.

Adding Two Values Example Script

This section describes how to create and execute a simple JavaScript debugger script that adds takes input and adds two numbers.

This simple script provides a single function, addTwoValues.

Use a text editor such as Notepad to create a text file named FirstSampleFunction.js

Use the .load (Load Extension DLL) command to load the JavaScript provider.

Use the .scriptload command to load the script.

After the script is loaded the additional functionality is available in the debugger. Use the dx (Display NatVis Expression) command to display Debugger.State.Scripts to see that our script is now resident.

We can select the FirstSampleFunction, to see what functions it provides.

To make the script a bit more convenient to work with, assign a variable in the debugger to hold the contents of the script using the dx command.

Use the dx expression evaluator to call the addTwoValues function.

You can also use the @$scriptContents built in alias to work with the scripts. The @$scriptContents alias merges all of the .Content of all of the scripts that are loaded.

When you are done working with the script use the .scriptunload command to unload the script.

Debugger Command Automation

This section describes how to create and execute a simple JavaScript debugger script that automates the sending of the u (Unassemble) command. The sample also shows how to gather and display command output in a loop.

This script provides a single function, RunCommands().

Use a text editor such as Notepad to create a text file named RunCommands.js

Use the .load (Load Extension DLL) command to load the JavaScript provider.

Use the .scriptload command to load the RunCommands script.

After the script is loaded the additional functionality is available in the debugger. Use the dx (Display NatVis Expression) command to display Debugger.State.Scripts.RunCommands to see that our script is now resident.

Use the dx command to call the RunCommands function in the RunCommands script.

Special JavaScript Debugger Functions

There are several special functions in a JavaScript script called by the script provider itself.

Script Debugger 7 0 5 – Applescript Authoring Environment Software Download

initializeScript

When a JavaScript script loads and is executed, it goes through a series of steps before the variables, functions, and other objects in the script affect the object model of the debugger.

• The script is loaded into memory and parsed.
• The root code in the script is executed.
• If the script has a method called initializeScript, that method is called.
• The return value from initializeScript is used to determine how to automatically modify the object model of the debugger.
• The names in the script are bridged to the debugger's namespace.

As mentioned, initializeScript will be called immediately after the root code of the script is executed. Its job is to return a JavaScript array of registration objects to the provider indicating how to modify the object model of the debugger.

invokeScript

The invokeScript method is the primary script method and is called when .scriptload and .scriptrun are run.

uninitializeScript

The uninitializeScript method is the behavioral opposite of initializeScript. It is called when a script is unlinked and is getting ready to unload. Its job is to undo any changes to the object model which the script made imperatively during execution and/or to destroy any objects which the script cached.

If a script neither makes imperative manipulations to the object model nor caches results, it does not need to have an uninitializeScript method. Any changes to the object model performed as indicated by the return value of initializeScript are undone automatically by the provider. Such changes do not require an explicit uninitializeScript method.

Summary of Functions Called by Script Commands

This table summarizes which functions are called by the script commands

Use this sample code to see when each function is called as the script is loaded, executed and unloaded.

Creating a Debugger Visualizer in JavaScript

Custom visualization files allow you to group and organize data in a visualization structure that better reflects the data relationships and content. You can use the JavaScript debugger extensions to write debugger visualizers which act in a way very similar to NatVis. This is accomplished via authoring a JavaScript prototype object (or an ES6 class) which acts as the visualizer for a given data type. For more information about NatVis and the debugger see dx (Display NatVis Expression).

Example class - Simple1DArray

Consider an example of a C++ class which represents a single dimensional array. This class has two members, m_size which is the overall size of the array, and m_pValues which is a pointer to a number of ints in memory equal to the m_size field.

We can use the dx command to look at the default data structure rendering.

JavaScript Visualizer

In order to visualize this type, we need to author a prototype (or ES6) class which has all the fields and properties we want the debugger to show. We also need to have the initializeScript method return an object which tells the JavaScript provider to link our prototype as a visualizer for the given type.

Save the script in a file named arrayVisualizer.js.

Use the .load (Load Extension DLL) command to load the JavaScript provider.

Use .scriptload to load the array visualizer script.

Now, when the dx command is used the script visualizer will display rows of array content.

In addition, this JavaScript visualization provides LINQ functionality, such as Select.

What Affects the Visualization

A prototype or class which is made the visualizer for a native type through a return of a host.typeSignatureRegistration object from initializeScript will have all of the properties and methods within JavaScript added to the native type. In addition, the following semantics apply:

• Any name which does not start with two underscores (__) will be available in the visualization.

• Names which are part of standard JavaScript objects or are part of protocols which the JavaScript provider creates will not show up in the visualization.

• An object can be made iterable via the support of [Symbol.iterator].

• An object can be made indexable via the support of a custom protocol consisting of several functions: getDimensionality, getValueAt, and optionally setValueAt.

Native and JavaScript Object Bridge

The bridge between JavaScript and the object model of the debugger is two-way. Native objects can be passed into JavaScript and JavaScript objects can be passed into the Debugger's expression evaluator. As an example of this, consider the addition of the following method in our script:

This method can now be utilized in the example LINQ query above. First we load the JavaScript visualization.

Then we can use the multiplyBySeven function inline as shown below.

Conditional Breakpoints with JavaScript

You can use JavaScript to do supplemental processing after a breakpoint is hit. For example, script can be used to examine other run time values and then determine if you want to automatically continue code execution or stop and do additional manual debugging.

For general information on working with breakpoints, see Methods of Controlling Breakpoints.

DebugHandler.js Example Breakpoint Processing Script

This example will evaluate notepad's open and save dialog: notepad!ShowOpenSaveDialog. This script will evaluate the pszCaption variable to determine if the current dialog is an 'Open' dialog or if it is a 'Save As' dialog. If it's an open dialog, code execution will continue. If it's a save as dialog, code execution will stop, and the debugger will break in.

Use the .load (Load Extension DLL) command to load the JavaScript provider.

This command sets a breakpoint on notepad!ShowOpenSaveDialog, and will run the script above whenever that breakpoint is hit.

Then when the File > Save option is selected in notepad, the script is run, the g command is not sent, and a break in code execution occurs.

Work With 64-Bit Values in JavaScript Extensions

This section describes how 64-bit values passed into a JavaScript debugger extension behave. This issue arises as JavaScript only has the ability to store numbers using 53-bits.

64-Bit and JavaScript 53-Bit Storage

Script Debugger 7 0 5 – Applescript Authoring Environment Software Pdf

Ordinal values passed into JavaScript are normally marshaled as JavaScript numbers. The problem with this is that JavaScript numbers are 64-bit double precision floating point values. Any ordinal over 53-bits would lose precision on entry into JavaScript. This presents an issue for 64-bit pointers and other 64-bit ordinal values which may have flags in the highest bytes. In order to deal with this, any 64-bit native value (whether from native code or the data model) which enters JavaScript enters as a library type -- not as a JavaScript number. This library type will round trip back to native code without losing numeric precision.

Auto-Conversion

The library type for 64-bit ordinal values supports the standard JavaScript valueOf conversion. If the object is used in a math operation or other construct which requires value conversion, it will automatically convert to a JavaScript number. If loss of precision were to occur (the value utilizes more than 53-bits of ordinal precision), the JavaScript provider will throw an exception.

Note that if you use bitwise operators in JavaScript, you are further limited to 32-bits of ordinal precision.

This sample code sums two numbers and will be used to test the conversion of 64 bit values.

Use a text editor such as Notepad to create a text file named PlayWith64BitValues.js

Use the .load (Load Extension DLL) command to load the JavaScript provider.

Use the .scriptload command to load the script.

To make the script a bit more convenient to work with, assign a variable in the debugger to hold the contents of the script using the dx command.

Use the dx expression evaluator to call the addTwoValues function.

First we will calculate the value of 2^53 =9007199254740992 (Hex 0x20000000000000).

First to test, we will use (2^53) - 2 and see that it returns the correct value for the sum.

Then we will calculate (2^53) -1 =9007199254740991. This returns the error indicating that the conversion process will lose precision, so this is the largest value that can be used with the sum method in JavaScript code.

Call a data model method passing 64-bit values. There is no loss of precision here.

Comparison

The 64-bit library type is a JavaScript object and not a value type such as a JavaScript number. This has some implications for comparison operations. Normally, equality () on an object would indicate that operands refer to the same object and not the same value. The JavaScript provider mitigates this by tracking live references to 64-bit values and returning the same 'immutable' object for non-collected 64-bit value. This means that for comparison, the following would occur.

Use a text editor such as Notepad to create a text file named ComparisonWith64BitValues.js

Use the .load (Load Extension DLL) command to load the JavaScript provider.

Use the .scriptload command to load the script.

Script Debugger 7 0 5 – Applescript Authoring Environment Software Downloads

To make the script a bit more convenient to work with, assign a variable in the debugger to hold the contents of the script using the dx command.

First to test, we will use (2^53) - 2 and see that it returns the expected values.

We will also try the number 42 as the first value to validate the comparison operator is working as it should.

Then we will calculate (2^53) -1 =9007199254740991. This value returns the error indicating that the conversion process will lose precision, so this is the largest value that can be used with the comparison operators in JavaScript code.

Maintaining Precision in Operations

In order to allow a debugger extension to maintain precision, a set of math functions are projected on top of the 64-bit library type. If the extension needs (or may possibly) need precision above 53-bits for incoming 64-bit values, the following methods should be utilized instead of relying on standard operators:

JavaScript Debugging

This section describes how to use the script debugging capabilities of the debugger. The debugger has integrated support for debugging JavaScript scripts using the .scriptdebug (Debug JavaScript) command.

Note

To use JavaScript Debugging with WinDbg Preview, run the debugger as Administrator.

Use this sample code to explore debugging a JavaScript. For this walkthrough, we will name it DebuggableSample.js and save it in the C:MyScripts directory.

Load the sample script.

Start actively debugging the script using the .scriptdebug command.

Once you see the prompt >>> Debug [DebuggableSample

At this point, you are back in the normal debugger. Execute the following command to call the script.

Now, you are back in the script debugger and broken in on the first line of the outermost JavaScript function.

In addition to seeing the break into the debugger, you get information on the line (73) and the column (5) where the break tookplace as well as the relevant snippet of source code: var x = 99.

Let's step a few times and get to another place in the script.

At this point, you should be broken into the throwAndCatch method on line 34.

You can verify this by executing a stack trace.

From here, you can investigate the value of variables.

Let's set a breakpoint on the current line of code and see what breakpoints are now set.

From here, we'll disable the entry (en) event using the sxd script debugger command.

And then just go and let the script continue to the end.

Execute the script method again and watch our breakpoint be hit.

Display the call stack.

At this point, we want to stop debugging this script, so we detach from it.

And then type q to quit.

Executing the function again will no longer break into the debugger.

JavaScript in VSCode - Adding IntelliSense

If you would like to work with the debugger data model objects in VSCode, you can use a definition file that is available in the Windows development kits. The IntelliSense definition file provides support for all of the host.* debugger object APIs. If you installed the kit in the default directory on a 64 bit PC, it is located here:

C:Program Files (x86)Windows Kits10Debuggersx64winextJsProvider.d.ts

To use the IntelliSense definition file in VSCode:

1. Locate the definition file - JSProvider.d.ts

2. Copy the definition file to same folder as your script.

3. Add /// to the top of your JavaScript script file.

With that reference in your JavaScript file, VS Code will automatically give you IntelliSense on the host APIs provided by JSProvider in addition to the structures in your script. For example, type 'host.' and you'll see IntelliSense for all the available debugger model APIs.

JavaScript Resources

The following are JavaScript resources that may be useful as you develop JavaScript debugging extensions.

Related topics