Hyperledger Fabric Debugger for Visual Studio Code
Hyperledger Fabric Debugger Plugin by Spydra is an Extension for Visual Studio Code that makes it easy for developers to build and debug Chaincode right from within the IDE. Typically, developing Chaincode for Fabric requires developers to set up a Fabric environment, deploy the developed Chaincode to it and then debug it by printing log messages to the console. In addition, installing a new version of Chaincode in a Fabric network is not as simple as uploading the new code. Developers have to execute the chaincode lifecycle commands for every modification to upgrade the Chaincode. This makes it very difficult to develop code in an iterative manner.
By using the Hyperledger Fabric Debug Plugin, a developer does not need to set up a Hyperledger Fabric network to deploy and test Chaincode. The plugin will automatically set up a local Fabric environment and manage the process of installing the Chaincode.
You can use the Add Configuration button on the launch.json page and choose either "Go: Debug Fabric Chaincode" or "Node.js: Debug Fabric Chaincode" options to add the required launch configuration.
Additional configuration options that are supported natively by the Go and Node.js language debuggers can also be added if needed.
For a list of additional options supported by Go Debugger, please refer to Go launchjson-attributes.
For a list of additional options supported by Node.js Debugger, please refer to Node.js launchjson-attributes.
Start debugging as you would normally do by pressing F5 or select the Run and Debug button from the Run view. Typical debug functionalities provided by the Go and Node.js debugger for VS Code like setting a breakpoint, stepping in/stepping over, viewing variables, stack trace etc. are all supported.
Manage Local Fabric Network
The Hyperledger Fabric Debugger automatically creates a local Fabric network with a single organization, one orderer, one peer with CouchDB and one ca node. The network is created in Docker as containers. When you exit VS Code, the nodes that belong to this network are automatically stopped, but the containers are not removed. Due to this, any Ledger data is presisted across VS Code or even Docker/machine restarts.
The extension provides various ways to manage the local Fabric network. For e.g if you want to remove the Docker containers or simply reset the network to remove any Ledger data. Navigate to the Hyperledger Debugger Explorer by clicking the logo on the left pane. The following actions can be performed on the local network.
Manage Wallet Identities
By default, the extension, creates two users - one user 'Org1Admin' with an Admin NodeOU role and one user 'User1' with a Client NodeOU role for testing. Navigate to the Hyperledger Debugger Explorer to create additional identities that can be used for testing.
For creating additional identities, click the + icon against the organization that you want the identity to be created for and provide a username. These identities can subsequently be used while submitting transactions.
For remove an identity, click the X icon against the corresponding identity.
Submit Transactions to Chaincode
Once the breakpoints are set up and the Debugger is launched, in order for the code to execute and hit the breakpoint, the corresponding Chaincode method has to be invoked with the right arguments. This is similar to debugging an API wherein a request to the API has to be made. The Hyperledger Fabric extension supports invoking Chaincode methods directly from VS Code.
Create a .fabric file anywhere in the project. The .fabric file is a JSON file in which you can add the details of one or more Chaincode methods that you want to invoke as well as arguments to be supplied and identity to be used. You can define multiple requests in one file as well as you can create multiple files as needed. e.g
The various keys supported for each request object are:
Click on "Send Request" link that appears at the top of each of the method. The response will be displayed in a separate window that appears.
Frequently Asked Questions
1. Debugging fails for Go Chaincode with the following error "Failed to launch: could not launch process: not an executable file " or with the error "Build Error: go build -o /.vscode/__debug_bin -gcflags all=-N -l . no Go files in /.vscode (exit status 1)"
For the Go Debugger to work properly, you need to select the file which contains the main() function first and then start debugging. Alternatively, in the .vscode/launch.json file, add an additional field called "program" that points to the file that contains the main() function in the Chaincode. For e.g.
2. I've installed the extension, but when I debug a Go Chaincode, I get the error "Error starting chaincode: 'CORE_CHAINCODE_ID_NAME' must be set"
This typically happens when the launch.json file is not created with the right debug settings. The launch.json file specifies that the Hyperledger Fabric debugger extension has to be used instead of the regular Go Debugger. Create the launch settings file as mentioned here.
3. I've installed the extension, but when I debug a Node.js Chaincode, nothing happens. The debugger starts and stops immediately
This typically happens when the launch.json file is not created with the right debug settings. The launch.json file specifies that the Hyperledger Fabric debugger extension has to be used instead of the regular Node.js Debugger. Create the launch settings file as mentioned here.
4. I've installed the extension and started the local fabric network also. When I submit a transaction in the .fabric file, I get an error "Start the Network or Start Debugging(F5) before submitting a transaction to Fabric"
Even though the local fabric network is started, in order for you to submit a transaction defined in the .fabric file, the Chaincode has to be started in Debug mode. Press F5 or select the Run and Debug button from the Run view to start debugging.
5. When I start debugging the Chaincode, I get the error "error starting chaincode: ccid must be specified"
This usually means that the Chaincode that you are trying to debug is developed using the Fabric External Chaincode as a Service model. Stop debugging, set the property "isCaas":true in the .vscode/launch.json file and start debugging again.
6. When I start debugging the Chaincode, I get a message "You don't have an extension for debugging 'JSON with Comments'"
This typically means that the launch.json file is not created. Create the launch settings file as mentioned here, select the code file that contains the entry point for the Chaincode and start debugging again.