NSO IDE

This is the codebase for the NSO IDE Visual Studio Code extension.

Pre-requisites

Ensure the following are installed

• JDK 11 is installed
• Python is installed

Supported Functionality

The aim of this extension is to provide a better user experience for developers wanting to develop their own NSO services. At this point in time reactive fastmap and nano services are not supported using the IDE. In terms of NSO package - the IDE supports Yang, XML, Java and Python and brings together various elements required to create a simple service.

Please see detailed information below for supported functionality.

Make Package

Use this command to create a new package. The aim of this command is to provide functionality similar to ncs-make-package. It will create the basic structure for you to start developing a new service package.

• In VSCode, go to View -> Command Palette -> NSO: Make Package
• Select Java Package or Python Package or Template Package.
• A wizard should show up with input fields for Package Name, Package Location, Namespace, Prefix and Yang Version, add Nano service checkbox
• Check the Create Nano Service checkbox to generate nano service package
• To create a Template Package with pre- and post-modification templates, ensure you select the Create with Pre and Post Modification Template checkbox. If this checkbox is not selected, a standard template package will be created instead.
• Your system NCS_DIR will be populated for the NSO Installation directory, however you may omit it or define a different path. This is used only for discovering YANG packages.
• To apply specific restrictions before creating the Python package, users can select one or more checkboxes under Python Specific Options, which include: component-class NAME, disable-service-example, action-example, subscriber-example, and validation-example.
• Click Create Package once all required fields have been entered
• NSO IDE will create the required package and open a new instance of VSCode Editor with NSO Package already open

If an NSO directory is not specified, you will need to set up yang.settings in your new project.

Open Existing Package

Use this command to open an existing package.

• In VSCode, go to View -> Command Palette -> NSO: Open Existing Package
• A Dialog box should pop up allowing you to select the package folder
• Select the folder and click Open

Editing Yang Files

Opening yang file will allow for syntax highlighting of Yang keywords. For Yang support, a 3rd party extension called Yangster is used. Yangster is also able to resolve imports for core NSO models but requires additional configuration.

Add NSO Yang Models for Yangster

Packages created with the Make Package wizard will contain a yang.settings file in the package root. This file contains the root path for discovering YANG modules.

The Yangster language server will show errors for missing packages without this configuration. If your package does not have the yang.settings file, you may want to create it with the following contents:

{
  "yangPath": "path/to/yang"
}

Typically, the path will be $NCS_DIR/src/ncs/yang for your NSO installation, but this can be changed. Indexing the YANG modules can take several minutes the first time, after which missing package errors should disappear.

Yang Diagram

This is a feature that is provided by the Yangster extension.

• Update the Yang File as required
• Typing Ctrl+space can bring up auto completion where appropriate
• Right-Click on the Editor and select "Open in Diagram"

Adding a new Yang Module

• In the Explorer View, navigate to Yang Folder and select it
• Right Click on Yang Folder or click on the "+" icon on top of explorer pane to launch Add Yang Module Wizard
• In the Wizard, fill the input fields for Module Name, Namespace, Prefix and Yang Version
• Click Finish

Add Service Point

Often whilst working on a package, there is a requirement to create a new service. This usually involves adding service-point. Adding a service point also requires other parts of the files to be updated, e.g. Python.

Service points are usually added to lists in yang models.

• Update your yang model as required
• The IDE automatically detects lists elements and above the list, you will find code lenses for "Add Python Service Point" and "Add Java Service Point"
• Click on "Add Python/Java Service Point" link depending on your developing language
• Fill in the required details
• The form allows various options in terms of creating a new python module or using an existing python module, if python was selected
  • If an existing python module is selected, it is assumed that you're selecting the correct module and it's been created correctly, i.e. the package-meta-data.xml file has been updated with component definition
  • if the wizard is used to create a new python file, it will update the relevant sections in package-meta-data.xml
  • Ensure the Service Class Name is populated
• If adding a Java Service Point, the yang model will be updated with a servicepoint element, package-meta-data file with a new component and a new Java class will be created with service code skeleton code

Register Action Point

Any action-point in a yang model must be registered in NSO. Registering an action point also requires other parts of the files to be updated, e.g. Python ( register register_action) and update package-meta-data if needed.

Action points are usually define in lists or containers.

• Update your yang model as required
• The IDE automatically detects actionpoint elements in yang , you will find code lenses "Register Python Action Point" and "Register Java Action Point"
• Click on "Register Python Action Point" to create files/code for python or "Register Java Action Point" to create files structures for Java to handle the action point
• Fill in the required details
• The form allows various options for Python in terms of creating a new python module or using an existing python module
• If an existing python module is selected, it is assumed that you're selecting the correct module and it's been created correctly, i.e. the package-meta-data.xml file has been updated with component definition
• if the wizard is used to create a new python file or a Java action point is being added, it will update the relevant sections in package-meta-data.xml
• Ensure the Action Class Name is populated

Editing Python Files

Opening a python file will utilize Microsoft's Pylance extension. This extension provides syntax highlighting and other features such as code completion etc as standard.

Adding a new Python Module

• In the Explorer View, navigate to Python Folder and select it
• Right Click on Python Folder or click on the "+" icon on top of explorer pane to launch Add Python Module Wizard
• In the Wizard, fill the input fields for Module Name, Component Name and Class Name
• Click Finish

Python NSO Code Completion (Snippets)

• Open a python file for editing
• When IDE detects text which matches pre-defined snippets, options will be shown
  • Currently, "maapi" will show options for creating maapi write transaction and "ncs" will show snippet for ncs template and variables
• When a snippet is selected, it will insert the code and also highlight config items that can be changed. Press Tab to cycle through each value

Java NSO Code Completion (Snippets)

• Open a java file for editing.

• When IDE detects text which matches pre-defined snippets, options will be shown

  • Currently following snippets are supported in java file
  1. "maapi_conection", "maapi" or "session": It will show options for opening socket and start startUserSession.
  2. "template" or "Template": It will show option for ncs template and variables with apply template function call.
  3. "ServiceCallback" or "@ServiceCallback": It will show the option for ServiceCallback function with arguments.
  4. "ActionCallback" or "@ActionCallback": It will show the option for ActionCallback function with arguments.
  5. "NanoServiceCallback" or "@NanoServiceCallback" : It will show the option for NanoServiceCallback function with arguments.

• When a snippet is selected, it will insert the code and also highlight config items that can be changed. Press Tab to cycle through each value

Editing XML Template Files

The final part of a typical service development is creating and editing XML configuration template

Adding a new XML template

• In the Explorer View, navigate to templates Folder and select it
• Right Click on templates Folder or click on the "+" icon on top of explorer pane to launch Add XML Template Wizard
• In the Wizard, fill in the Template Name field
• Click Finish

XML Code Completion

Processing Instructions & Variables

• Open XML file for editing
• When IDE matches text which match defined snippets, options will be shown
• Processing Instructions
  • All processing instructions supported are added as snippets, typing in <? followed by character will trigger the auto completion
• $ Variables
  • Variables defined in xml template via "<?set" processing instruction or defined in python code should be shown when a user types in $ followed by character matching variable name
• Auto completion can also be triggered by pressing Ctrl+Space
• Upon selecting an option, the relevant XML processing instructions or Variable will be inserted and also highlight items that require user updates. Pressing Tab will cycle through items

Nano Viewer

The Nano Viewer is a visual tool for inspecting Nano Plan modules. The Nano Viewer is accessible via a Code Lens above ncs:nano-plan and ncs:service-behavior-tree statements. The Nano Viewer is currently read-only, but supports live updates as the corresponding Yang data is modified.

Highlighting Source Code in Nano Viewer

Plan-outline

• When clicking on the plan-outline in the Nano Viewer code lens, it displays a list of component types.
• Users can click on a component-type name to see the highlighted sections in the YANG file.
• Users can expand the component-type to view a list of states for that particular component-type.
• Hovering over a particular component type or arrow sign shows Click to go to source. Clicking this will display the source code of the selected component and move the cursor to the corresponding part of the YANG file.
• When a user clicks on a specific state name, the corresponding part in the YANG file is highlighted.
• The states under the selected component are shown, and hovering over a state shows Click to go to source. Clicking on a state displays its source code.

Behavior-tree

• When clicking on behavior-tree in the Nano Viewer code lens, it displays the selector. Clicking this shows the component with a component-type-ref.
• Hovering over the component-type-ref shows Click to go to source. Clicking this will display the source code of the selected component and move the cursor to the corresponding part of the YANG file.
• The same highlight feature has been added to the Nano-Behavior Tree Viewer when clicking on a component-type-ref.

Template Tester

The Template Tester facilates designing and testing NSO XML templates by allowing the user to upload the template directly to NSO, test the template against a NSO service and see the diff results of applying the new changes all from a webview panel that is accessible via a Code Lens Open NSO Template Tester at the top of an XML template.

The extension communicates with NSO via JSON-RPC so it is necessary that the NSO webui configuration is enabled in ncs.conf.

By default the Template Tester will use NSO's default settings to connect to NSO when Redeploying Package or Reloading Package to upload template changes and when Testing Template. The host, port, username and password of the NSO server in configurable with by changing the default values in the input textfields. NSO servers configuration can also be saved and reused by creating an entry in the NSO.Instance list in the settings.json file like so:

"NSO.Instance": [
  {
    "name": "Local NSO",
    "host": "127.0.0.1",
    "port": 8080,
    "username": "admin",
    "password": "admin",
    "scheme": "http",
  }
]

which can then be selected from the dropdown at the top of the Template Tester webview.

An example flow of designing or testing a template would go as followed:

1. Create or open existing XML template.
2. Update XML template and/or service code.
3. Click on Code Lens on top of XML file to open Template Tester.
4. Provide NSO server information or chose server from dropdown.
5. Press Redeploy Package button to upload template to NSO server. If package redeploy result is false press Reload Package button to get reason why package redeploy failed.
6. Provide keypath of already deployed NSO service to XML template agains.
7. See Result textarea for resulting diff of applying new template changes.
8. Check the 'Debugger details' checkbox to view the debug information of the template.
9. Rinse and repeat.

Note that the Redeploy Package feature only works if the package-meta-data.xml file is at the root of the opened folder, since we need to figure out the package name to re-deploy.

Note that the debugger details feature is only supported in NSO-6.4 and later versions.

Validations

• If a user enters a variable in XML template that isn't detected, user will be shown a warning
• If Processing instruction end tags do not match, error messages will also be shown

Limitations

The IDE is designed to provide help on a best effort basis. This means that if something is not correct, where possible, the NSO IDE extension will aim to provide meaningful error messages or warnings, however, it's not designed for 100% coverage. Example of such limitations include not being able to detect template variables where the variable name has been defined in some python variable else where and being passed.

vars.add('IP_ADDRESS','192.168.0.1')

In the above example, NSO IDE will detect that a template variable IP_ADDRESS has been set

ip_add_var_name = 'IP_ADDRESS'
vars.add(ip_add_var_name, '192.168.0.1')

However, whilst the code achieves the same objective, the above will not be detected.

Debug NSO Python Package: Service and Actions

The Python Debugger extension is automatically installed along with the Python extension for VS Code. It offers debugging features with debugpy for several types of Python applications, including scripts, web apps, remote processes and more.

To verify it's installed, open the Extensions view and search for @installed python debugger. You should see the Python Debugger extension listed in the results.

Initialize configurations

A configuration drives VS Code's behavior during a debugging session. Configurations are defined in a launch.json file that's stored in a .vscode folder in your workspace.

Note: To change debugging configuration, your code must be stored in a folder.

If you don't yet have any configurations defined, you'll see a button to Run and Debug and a link to create a configuration (launch.json) file:

To generate a launch.json file with Python configurations, do the following steps:

1. Select the create a launch.json file link (outlined in the image above) or use the Run > Open configurations menu command.

2. Select Python Debugger from the debugger options list.

3. A configuration menu will open from the Command Palette allowing you to choose the type of debug configuration you want to use for our Python project file. So for NSO debug, select Remote Attach in the Select a debug configuration menu that appears.

Then you have to provide hostname or IP address and port number

You should see something like that :

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger: Remote Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "127.0.0.1",
                "port": 8080
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "."
                }
            ]
        }
    ]
}

Save the file and you should have a "Python Debugger: Remote Attach" debug setting with a run button at the top left.

Now you have to install debugpy using python -m pip install --upgrade debugpy into your Python environment.

In the main.py file, class Main, method setup(), of your NSO package put the line :

debugpy.listen(8080)

This will open the port of the debug server after a package reload or a package redeploy. Don't forget to remove it after debugging It's also possible to change the ip address of the debug server by providing a tuple (ip_adress,port) for example:

debugpy.listen(('0.0.0.0', 8080))

Now we must put a breakpoint. There are two ways to put a breakpoint one is programmatic breakpoint and another is graphical red breakpoint. The graphical red breakpoint will only be triggered if you provide the correct remoteRoot at pathMappings at .vscode/launch.json

Ok so you can do a package reload to run the debug server and to take the breakpoint into account. To connect to the debug server click on the green triangle.

A list appears in the "Call Stack" section in the UI :

If you launch your action or service from cli, you'll see the arrow on the next instruction to be executed in the code if you put the correct remoteRoot path at launch.json .

If you are getting error like this below:

Or

It means you have not update or properly configure the remoteRoot path. To properly configure the remoteRoot path check the demo example:

1. Initially Update the remoteRoot path to / instead of .
2. ReRun the debug server by clicking on the green triangle.
3. Rerun the action from cli, it stop at breakpoint and open a new file with error like this:

4. Now you have to take this path that mention at top in case of example it is "/Users/akshaybisht/ncs-run/state/packages-in-use/1/host_python21" copy that path at remoteRoot path at launch.json 5. Restart the debug server again it and run you action again.

That's it, now you're able to debug your NSO package with VS Code

Debugging NSO Java Package: Service and Actions

This guide provides detailed instructions for setting up and debugging an NSO (Network Services Orchestrator) Java package. Follow the steps below to configure the NSO environment, start the Java VM in debug mode, and attach your debugger to troubleshoot the service and actions.

Prerequisites

• NSO installed and running.
• Java Development Kit (JDK) installed.
• An Integrated Development Environment (IDE) with Java debugging capabilities.
• Visual Studio Code (VSCode) with the Extension Pack for Java installed.

Steps to Debug NSO Java Package

1. Ensure VSCode Extension Pack for Java is Installed

   Before proceeding, make sure you have installed the Extension Pack for Java in VSCode. This pack includes essential tools like the Language Support for Java(TM) by Red Hat, Debugger for Java, Java Test Runner, Maven for Java, and Visual Studio IntelliCode.

   • Open VSCode.

   • Go to the Extensions view by clicking the Extensions icon in the Activity Bar on the side of the window or by pressing Ctrl+Shift+X.

   • In the Extensions view search box, type Extension Pack for Java.

   • Click Install to install the pack.

     

2. Stop Auto-Start of Java VM

   To prevent the Java VM from starting automatically, you need to update the ncs.conf file. This configuration file typically resides in the NSO installation directory.

   • Open the ncs.conf file in a text editor.

   • Add the following configuration to disable auto-start for the Java VM:

     <java-vm>
         <auto-start>false</auto-start>
     </java-vm>
     

3. Restart NSO in Debug Mode

   Restart NSO with the Java VM in debug mode. This will enable the Java VM to listen for debug connections on port 9000.

   • Open a terminal.

   • Execute the following command to start NSO in debug mode:

     ncs-start-java-vm -d

     This command starts the Java VM in debug mode, listening on port 9000.

4. Configure Your IDE for Remote Debugging**

   To attach your IDE to the running Java VM for debugging, you need to configure the IDE's debugger settings. Here, we will provide an example configuration for VS Code.

   • Open your project in VS Code.

   • Update the launch.json file with the remote debugging configuration. The launch.json file is typically located in the .vscode directory of your project. Add the following configuration:

     {
         "version": "0.2.0",
         "configurations": [
             {
                 "type": "java",
                 "name": "Attach to Remote Java VM",
                 "request": "attach",
                 "hostName": "localhost",
                 "port": 9000
             }
         ]
     }
     

   • Save the launch.json file.

5. Attach the Debugger

   • In VS Code, open the Run and Debug view by clicking on the debug icon in the Activity Bar on the side of the window.
   • Select "Attach to Remote Java VM" from the configuration dropdown.
   • Click the green play button to start the debugger.

6. Run the Action

   Trigger the action you want to debug in your NSO environment. The debugger in your IDE will catch the breakpoints and allow you to step through the code.

Example Workflow to Debug Java NSO package

Detailed User Guide info for NSO Plugins

• URL: https://developer.cisco.com/docs/nso/guides/#!nso-developer-studio/nso-developer-studio

Contribute

If you feel certain code snippets would be helpful or would like to help contribute to enhance the Extension, please get in touch: nsovscode@cisco.com