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