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 functionalily

The aim of this extension is to provide a better user experience for developers wanting to develop their own NSO services. The focus of the first release is to show how the NSO-IDE extension can be used to create a simple NSO service. 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 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 pacakge.

In VSCode, go to View -> Command Palette -> "NSO: Make Package"
A wizard should show up with input fields for Package Name, Package Location, Namespace, Prefix and Yang Version
Your system NCS_DIR will be populated for the NSO directory, however you may omit it or define a different path. This is used only for discovering YANG packages.
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

In the explorer pane, at the root of the folder, create a new file "yang.settings"
Copy the Path where NSO Source Yang files are stored
Enter the following JSON { "yangPath": "< path to yang files >" }
If on Windows, please ensure the backslash is escaped.
Save the file
The first time after updating the yangPath, the Yangster app will index and parse the yang file so it can resolve NSO imports - this process can take several minutes the first time.
No errors can be seen now for Yang files

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 whist 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.

Update your yang model as required
The IDE automatically detects lists elements and above the list, you will find a code lens for "Add Service Point"
Click on "Add Service Point" link
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 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 pacakge-meta-data.xml
- Ensure the Service Class Name is populated

Register Action Point

Any action-point in yang model must be reguster into NSO. Registering a 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 to lists or containers.

Update your yang model as required
The IDE automatically detects actionpoint elements in yang , you will find a code lens for "Add Action Point"
Click on "Add Action Point" link
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 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 pacakge-meta-data.xml
Ensure the Action Class Name is populated

Editing Python Files

Opening a python file will utilise Microsofts' 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

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 snipopets, 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

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. e.g.

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.

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

NSO Developer Studio - Developer IDE

Cisco Crosswork NSO