Giter Club home page Giter Club logo

vscode-dtdl's Introduction

DTDL Editor for Visual Studio Code

πŸŽ‰ Exciting Update: Our VSCode extension now offers expanded DTDL v3 support!

We are incredibly delighted to announce the latest update to our VSCode extension. Not only does our enhanced release now fully support the DTDL V3 context, but it also boasts improved Intellisense for V3 language extensions.

This comprehensive support includes crucial features such as historization, overriding, annotations, and quantitativeTypes, making our product more robust and versatile for your diverse developing needs.

Don't wait any longer! Dive in and discover the expanded functionality that our updated VSCode extension has to offer. Stay tuned to our repository for upcoming updates. We always welcome your invaluable insights and feedback for continued improvements.

Happy coding to all!πŸš€

Overview

The Digital Twin Definition Language (DTDL) is a language for describing models for Plug and Play devices, device digital twins, and logical digital twins. Broadly, modeling enables IoT solutions to provision, use, and configure digital twins of all kinds from multiple sources in a single solution. Using DTDL to describe any digital twin’s abilities enables the IoT platform and IoT solutions to leverage the semantics of each digital twin.

With the DTDL extension for Visual Studio Code , you can read and write documents using DTDL more efficiently taking full advantage of the following key features:

  • Create interfaces from the command palette with predefined or customized templates.
  • Intellisense to help you with the language syntax (including auto-completion).
  • Use predefined code snippets to develop DTDL efficiently.
  • Syntax validation.

Get Started

Create Interface

You could use the command palette to create interface from predefined or customized templates.

  • In Visual Studio Code, select View > Command Palette to open the VS Code command palette.
  • In the command palette, enter and run the command DTDL: Create Interface.
  • Follow the instruction to assign the interface name.
  • If there are multiple templates existing, choose a template you need. Otherwise, the extension will the basic template as default.
  • A JSON file will be created in the current folder. The file name is based on the interface name you assigned.
  • The @id is the path component of the Digital Twin Model Identifier (DTMI). You should modify the @id following the DTMI rule to uniquely identify the device model.

Intellisense and Syntax validation

This extension could help you with the language syntax (including auto-completion) and also validate the syntax with DTDL.

Use Predefined Code Snippets

Besides the basic auto completion, this extension also provides some predefined code snippets to help you develop DTDL efficiently.

Code Snippet Description
dtt Code snippet of telemetry
dtp Code snippet of property
dtc Code snippet of command

Create Your Own Template

Prepare your template file

You could use any DTDL file as a template to develop efficiently. Meanwhile, you could also use these predefined tags to make your template more flexible.

  • {modelId}: The extention will replace this tag with dtmi:com:example:interface_name;1 when creating a new DTDL from a template. For example, if you assigned the interface name as "test", the result will be dtmi:com:example:test;1.
  • {modelName}: The extension will replace this tag with the interface name when creating a new DTDL from a template.

Import your template file

  • Go to [extension installation location]/vsciot-vscode.vscode-dtdl-[extension release version]/templates
  • Store your template into this folder as a JSON file. Keep the file name short and meaningful, because the extension will use the file name as template name.

Create Your Own Code Snippets

If you would like to create customized code snippets for VS Code, you could follow Snippets in Visual Studio Code

Contribute Your Templates and Code Snippets to the Community

You could also contribute your templates and code snippets to the DTDL repository.

  • Uploading the new templates to templates folder.
  • Modifying and adding new code snippets to snippets/snippets.json file.

Once the pull request is approved, your templates and code snippets will be released with next release of DTDL extension.

Commands

Command Description
DTDL: Create Interface... Create new interface from predefined or customized templates.

Trouble Shooting

Error when creating the interface

As default, the extension will get the available templates from [extension installation location]/vsciot-vscode.vscode-dtdl-[extension release version]/templates. But if you delete this folder or all templates files in this folder, you will have an error when creating the interface. In order to fix this issue, you could copy the templates from DTDL repository to your local templates folder manually.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information please see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Contact Us

If you would like to help to build the best IoT experience with IoT Plug and Play, you can reach us directly at Gitter.

Telemetry

VS Code collects usage data and sends it to Microsoft to help improve our products and services. Read our privacy statement to learn more. If you don’t wish to send usage data to Microsoft, you can set the telemetry.enableTelemetry setting to false. Learn more in our FAQ.

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include Microsoft, Azure, DotNet, AspNet, Xamarin, and our GitHub organizations.

If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's Microsoft's definition of a security vulnerability, please report it to us as described below.

Reporting Security Issues

Please do not report security vulnerabilities through public GitHub issues.

Instead, please report them to the Microsoft Security Response Center (MSRC) at https://msrc.microsoft.com/create-report.

If you prefer to submit without logging in, send email to [email protected]. If possible, encrypt your message with our PGP key; please download it from the the Microsoft Security Response Center PGP Key page.

You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at microsoft.com/msrc.

Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:

  • Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
  • Full paths of source file(s) related to the manifestation of the issue
  • The location of the affected source code (tag/branch/commit or direct URL)
  • Any special configuration required to reproduce the issue
  • Step-by-step instructions to reproduce the issue
  • Proof-of-concept or exploit code (if possible)
  • Impact of the issue, including how an attacker might exploit the issue

This information will help us triage your report more quickly.

If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our Microsoft Bug Bounty Program page for more details about our active programs.

Preferred Languages

We prefer all communications to be in English.

Policy

Microsoft follows the principle of Coordinated Vulnerability Disclosure.

vscode-dtdl's People

Contributors

c-ryan-k avatar dependabot[bot] avatar digimaun avatar dilin-ms avatar elsie4ever avatar eriolchan avatar ivanjobs avatar microsoft-github-policy-service[bot] avatar microsoftopensource avatar msftgits avatar rido-min avatar ridomin avatar sldragon avatar yjin81 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

vscode-dtdl's Issues

Support virtual workspaces

πŸ‘‹ Hi there, Martin here, from the VS Code team.

Recently we've announced the Remote Repository feature that lets you browse and edit files and folders directly on GitHub.

Open Remote Repository... opens VSCode on a folder or workspace located on a virtual file system. We call this a virtual workspace. We observed that not all extension support this well, either because they can not, or they haven't thought about it.

It would be fantastic if you could test whether your extension can handle virtual workspaces:

Check out the Virtual Workspaces Extension Author Guide on how to do that.

When done, set the new virtualWorkspaces capability in your 'package.json'.

{
  "capabilities": {
    "virtualWorkspaces": true | false
  }
}
  • Use "virtualWorkspaces": true if your extension is prepared for virtual workspaces
  • Use "virtualWorkspaces": false if your extension should be disabled when a virtual workspace is opened

For questions and comments please use the Virtual Workspaces Tracking Issue.

Thanks for the support and the great work! ❀️

Semantic Types not supported on Fields

With DTDL v3 semantic types are allowed on Fields, as shown in the example from https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v3/DTDL.quantitativeTypes.v1.md

However this VSCode extension shows the next error for the interface below:

This Semantic Type can only be co-typed with type: Property, Telemetry

{
    "@context": [
        "dtmi:dtdl:context;3",
        "dtmi:dtdl:extension:quantitativeTypes;1"
    ],
    "@id": "dtmi:com:example:Sensor;1",
    "@type": "Interface",
    "contents": [
      {
        "@type": "Telemetry",
        "name": "multimeter",
        "schema": {
          "@type": "Object",
          "fields": [
            {
              "@type": [ "Field", "Temperature" ],
              "name": "thermometer",
              "schema": "double",
              "unit": "degreeCelsius"
            },
            {
              "@type": [ "Field", "Pressure" ],
              "name": "barometer",
              "schema": "double",
              "unit": "millibar"
            },
            {
              "@type": [ "Field", "RelativeHumidity" ],
              "name": "humidityMeter",
              "schema": "integer",
              "unit": "percent"
            },
            {
              "@type": [ "Field", "Velocity" ],
              "name": "anemometer",
              "schema": "double",
              "unit": "metrePerSecond"
            }
          ]
        }
      }
    ]
  }

Support co-types in @type element

The next valid DTDL is shown with errors

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:test;1",
  "@type": ["Interface", "NamedInterface"]
}

image

Support IRI as DTDL type

The following DTDL document produces two errors in the VSCode extension, although it's accepted by the parser

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:myThing;2",
  "@type": "Interface",
  "displayName": "myThing",
  "contents": [
    {
      "@id": "dtmi:com:example:myThing:temperature;1",
      "@type": "Telemetry",
      "name": "temperature",
      "dtmi:dtdl:property:schema;2": "double"
    }
  ]
}

Problems reported

[{
	"resource": "/C:/code/temp/scratch-repo/dtmi/com/example/mything-2.json",
	"owner": "_generated_diagnostic_collection_name_#0",
	"severity": 8,
	"message": "Miss required properties: schema",
	"startLineNumber": 7,
	"startColumn": 5,
	"endLineNumber": 7,
	"endColumn": 5
},{
	"resource": "/C:/code/temp/scratch-repo/dtmi/com/example/mything-2.json",
	"owner": "_generated_diagnostic_collection_name_#0",
	"severity": 8,
	"message": "dtmi:dtdl:property:schema;2 is not a valid property.",
	"startLineNumber": 11,
	"startColumn": 7,
	"endLineNumber": 11,
	"endColumn": 36
}]

Schema id not validated as required

DTDL v2 requires all schema elements to have an id, as reported by the parser:

{
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:test:schemas;1",
    "@type": "Interface",
    "schemas": [
        {
            "@type": "Object",
            "fields": [
                {
                    "name": "rf1",
                    "schema": "integer"
                }
            ]
        }
    ]
}
dtmi:test:schemas;1's property 'schemas' requires an identifer but none provided. Add an '@id' property whose value is a string that conforms to the DTMI syntax -- see https://github.com/Azure/digital-twin-model-identifier.

Current behavior. The Language server does not point this issue
Expected.

  • Show the issue in the problems tab
  • Squiggles
  • Show @id as required in the intellisense drop down

Support Relationships created by Central

Repro Steps

Create a Device Template in Central
Select Edge Device
Export the device template
Extract each of the interfaces to a different file

Expected: No errors since those are valid DTDL files
Observed:

The DTDL extension complains about the Relationship:

image

Although the files passes the .NET parser validations

Exported file
[
  {
    "@id": "dtmi:p8pl7l5ly:capabilitymodel:mybouqmfzo;1",
    "@type": "Interface",
    "contents": [
      {
        "@id": "dtmi:p8pl7l5ly:capabilitymodel:mybouqmfzo:SamplePnPModule;1",
        "@type": [
          "Relationship",
          "EdgeModule"
        ],
        "displayName": {
          "en": "SamplePnPModule"
        },
        "maxMultiplicity": 1,
        "name": "SamplePnPModule",
        "target": [
          "dtmi:p8pl7l5ly:SamplePnPModule;1"
        ]
      }
    ],
    "displayName": {
      "en": "Azure IoT Edge Capability Model mybouqmfzo"
    },
    "@context": [
      "dtmi:iotcentral:context;2",
      "dtmi:dtdl:context;2"
    ]
  },
  {
    "@id": "dtmi:p8pl7l5ly:SamplePnPModule;1",
    "@type": "Interface",
    "displayName": {
      "en": "Module SamplePnPModule"
    },
    "@context": [
      "dtmi:iotcentral:context;2",
      "dtmi:dtdl:context;2"
    ]
  }
]

Arrays in properties should show an error

Per the DTDL spec, properties do not support Arrays, using a model like the one below should report a problem.

For reference, the .NET parser fails with the next error:

dtmi:rido:dictionaries;1 has 'contents' value with name 'AMap' which contains Array, which is not allowed in 'schema' properties under elements of type Property. Remove the elements of type Array from 'schema' properties under the element of type Property.
{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:rido:dictionaries;1",
  "@type": "Interface",
  "displayName": "dictionaries",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "double"
    },
    {
      "@type": "Property",
      "name": "AMap",
      "writable": true,
      "schema": {
        "@type": "Map",
        "mapKey": {
          "name": "mapKey",
          "schema": "string"
        },
        "mapValue": {
          "name": "mapValue",
          "schema": {
            "@type": "Array",
            "elementSchema": "string"
          }
        }
      }
    },
    {
      "@type": "Command",
      "name": "reboot",
      "request": {
        "name": "delay",
        "schema": "integer"
      }
    }
  ]
}

Provide "quick fix" to add IoT Central context

When a model uses a type defined in the IoT Central context but the model does not specify this context, version 1.1.0 detects this condition and reports that the IoT Central context should be added. This is great, but ideally the extension should also provide a "quick fix" to add the missing context. It is merely a simple text substitution.

[Regression issue]the auto-completion and diagnostic function of schemas are wrong

Test on v0.2.0
Step:
1.input β€œβ€ in schemas value and verify the suggestion of auto-completion
image

Expect: should be no auto-completion suggestion
2.select one item from the suggestion list and verify no diagnostic message to reminder user to input DTMI
image

Expect:
The pattern of DTMI is dtmi:;. Path may contain only letters, digits, underscore, and colon. Version must be numeric.

Support Workspace Trust

Hello πŸ‘‹ I'm from the VS Code team.

Recently, we have been exploring a security feature we refer to as Workspace Trust. This feature is intended to centralize and unify a security conscious decision required by a variety of VS Code features. With workspace trust, the user will be able to declare whether or not they trust the folder that is opened in VS Code before these features are executed.

Why you should care

Your extension is incredibly popular with VS Code users! We want to make sure that those users have a delightful experience with workspace trust and that includes extension authors deciding how much of their extension is supported in an untrusted workspace.

Workspace Trust experience

You can enable the feature with the following setting security.workspace.trust.enabled. Once enabled, you will see the following dialog when opening folders in VS Code.

Workspace Trust Startup Dialog

This dialog is important for allowing the user to make a decision early and understand the impact of their decision. Once you understand the feature, you may want to customize when to display the dialog using the setting security.workspace.trust.startupPrompt.

You can follow the development of Workspace Trust and provide feedback in issue #106488.

Workspace trust API

First off, all of what I am about to say can be found in issue #120251. That issue will include discussion of the feature and any updates to the feature.

The Workspace Trust extension API is now in stable. This allowed us to release the first cut of our guide for onboarding your extension to Workspace Trust. The API is small, so here is a quick look.

You can declare your extension to provide complete, partial or no support in untrusted workspaces using the untrustedWorkspaces capability in package.json.

The following example declares that the extension is supported completely in untrusted workspaces. In this case, the extension is enabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": true
  }
}

The next example declares that the extension is not supported in untrusted workspaces. In this case, the extension is disabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": false
  }
}

The third option is to declared limited support. There are three tools provided to you when you select the limited option.

First, if you have a setting that can be configured in the workspace but requires the workspace to be trusted in order to apply the workspace value, then you can include the setting using restrictedConfigurations array property in untrustedWorkspaces object. Doing so, VS Code will ignore the workspace value of these restricted settings when your extension reads these settings values using the VS Code Workspace Configuration API.

The following example declares the settings that are restricted in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": "limited",
    "restrictedConfigurations": [
      "markdown.styles"
    ]
  }
}

Next, you can also check and listen if the current workspace is trusted or not programmatically using the following API:

export namespace workspace {
  /**
   * When true, the user has explicitly trusted the contents of the workspace.
   */
  export const isTrusted: boolean;
  /**
   * Event that fires when the current workspace has been trusted.
   */
  export const onDidGrantWorkspaceTrust: Event<void>;
}

Lastly, you can hide commands or views declaratively with the isWorkspaceTrusted context key in your when clauses.

A far more detailed guide on how to onboard which will be updated as we receive feedback can be found in issue #120251.

Rollout plan

Workspace Trust will remain disabled for the month of May, but we are planning on enabling this by default in the future. To prepare for that day, we would love for you to try it out and provide feedback.

We'd love your feedback

Since this issue was created in an automated fashion, we won't be monitoring the responses in this issue (our notifications would explode!). Instead we ask you to drop questions, and feedback in issue #120251 as we've mentioned above.

We're excited to see what you do with workspace trust!

Support the expanded format

Central and the Device Model Repository use the expanded format (an array with one item per interface) to import/export models with all the dependencies in the same file.

However this extension does not recognize that format and does not validate the DTDL

Invalid name in enum values not shown

In enum values like

          {
            "enumValue": "Compressed Air",
            "name": "Compressed Air"
          },

spaces in "name" attribute are not allowed, but not shown as error in editor.

DTDLValidator output:

*** Error parsing models
Error 1:
dtmi:digitaltwins:rec_3_3:core:Capability:_contents:__phenomenon:_schema:_enumValues:__Compressed Air;1's property 'name' has value 'Compressed Air', which is invalid. Modify the value of 'name' to make it match the regular expression '^[A-Za-z](?:[A-Za-z0-9_]*[A-Za-z0-9])?$'.
Primary ID: dtmi:digitaltwins:rec_3_3:core:Capability:_contents:__phenomenon:_schema:_enumValues:__Compressed Air;1
Secondary ID: 
Property: name

Location not accepted as a valid Semantic Type

This interface is reported as invalid, although the DTDL parser reports it as correct.

{
    "@context": "dtmi:dtdl:context;2",
    "@id": "dtmi:com:example:dnd:arraysDemos;1",
    "@type": "Interface",
    "contents": [
      {
          "@type": ["Telemetry", "Location"],
          "name": "multiplePoints",
          "schema": "point"
      }
    ]
  }

image

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.