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
- 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
- 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.
- 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 "Add Python Action Point" and "Add Java Action Point"
- Click on "Add Python Action Point" to create files/code for python or "Add 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
- "maapi_conection", "maapi" or "session": It will show options for opening socket and start startUserSession.
- "template" or "Template": It will show option for ncs template and variables with apply template function call.
- "ServiceCallback" or "@ServiceCallback": It will show the option for ServiceCallback function with arguments.
- "ActionCallback" or "@ActionCallback": It will show the option for ActionCallback function with arguments.
- "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.
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:
- Create or open existing XML template.
- Update XML template and/or service code.
- Click on Code Lens on top of XML file to open Template Tester.
- Provide NSO server information or chose server from dropdown.
- 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.
- Provide keypath of already deployed NSO service to XML template agains.
- See Result textarea for resulting diff of applying new template changes.
- 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.
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.
Detailed User Guide info for NSO Plugins
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