在应用中集成 Monaco 编辑器与 Kusto 查询语言支持

项目
10/02/2024

适用于：✅Azure 数据资源管理器

可以在应用中集成Monaco 编辑器与 Kusto 查询语言支持 (monaco-kusto)。将 monaco-kusto 集成到应用中可以提供编辑体验，例如完成、着色、重构、重命名和“转到定义”。它要求你针对身份验证、查询执行、结果显示和架构探索来构建解决方案。它为你提供了充分的灵活性，以打造适合你的需求的用户体验。

本文介绍如何将 monaco-kusto 添加到 Monaco 编辑器并将其集成到应用中。该包已在 GitHub 和 npm 上提供。

按照以下步骤使用 npm 将 monaco-kusto 集成到应用中。

第 1 步：安装 monaco-kusto 包

第 2 步：将应用设置为使用 monaco-kusto 包

第 3 步：将数据库架构添加到编辑器

尝试与我们的示例项目集成！

先决条件

Node.js（v6.10.3 或更高版本）

安装 monaco-kusto 包

安装 Monaco 编辑器 npm 包：
```
npm i monaco-editor
```
注意

若要自定义本机 Monaco 编辑器，请参阅 Monaco 编辑器 GitHub 存储库。
安装 monaco-kusto npm 包：
```
npm i @kusto/monaco-kusto
```

将应用设置为使用 monaco-kusto 包

可以使用以下方法之一将应用设置为使用 monaco-kusto：

AMD 模块系统
ESM (webpack)

将以下 HTML 添加到使用 Monaco 编辑器的页面，例如 index.html 文件。它们是必需的，因为该包对 kusto-language-service 存在依赖关系。

<script src="%PUBLIC_URL%/monaco-editor/min/vs/language/kusto/bridge.min.js"></script>
<script src="%PUBLIC_URL%/monaco-editor/min/vs/language/kusto/kusto.javascript.client.min.js"></script>
<script src="%PUBLIC_URL%/monaco-editor/min/vs/language/kusto/newtonsoft.json.min.js"></script>
<script src="%PUBLIC_URL%/monaco-editor/min/vs/language/kusto/Kusto.Language.Bridge.min.js"></script>

将 monaco 和 monaco-kusto 包中的静态文件复制到 Web 服务器上的 monaco-editor 文件夹中。你的应用将需要访问这些静态文件。
使用 monaco 来加载它们。有关示例，请参阅示例。

以下步骤介绍如何通过 webpack 将应用设置为使用 monaco-kusto。项目的默认入口点是 src/index.js 文件，默认配置文件是 src/webpack.config.js 文件。以下步骤假定你使用默认 webpack 项目设置来捆绑应用。

在配置文件中，添加以下代码片段：

在 resolve.alias 下，添加以下别名：

'vs/language/kusto/kustoMode': 'kustoMode',
'bridge.min': '@kusto/monaco-kusto/release/esm/bridge.min',
'kusto.javascript.client.min': '@kusto/monaco-kusto/release/esm/kusto.javascript.client.min.js',
'Kusto.Language.Bridge.min': '@kusto/monaco-kusto/release/esm/Kusto.Language.Bridge.min.js',
'Kusto': '@kusto/monaco-kusto/release/esm/Kusto.Language.Bridge.min.js',
'monaco.contribution': '@kusto/monaco-kusto/release/esm/monaco.contribution'

在 module.rules 下，添加以下加载程序和依赖项：

// Loaders
{ test: /bridge\.js/, parser: { system: false } },
{ test: /kusto\.javascript\.client\.min\.js/, parser: { system: false } },
{ test: /Kusto\.Language\.Bridge\.min\.js/, parser: { system: false } },
{ test: /kustoLanguageService/, parser: { system: false } },
// Dependencies
{ test: /Kusto\.Language\.Bridge\.min/, loader: 'exports-loader?window.Kusto!imports-loader?bridge.min,kusto.javascript.client.min' },
{ test: /kustoMonarchLanguageDefinition/, loader: 'imports-loader?Kusto' },

在 entry 下，添加以下入口点。记下返回的工作器路径，稍后会用到它。
```
`@kusto/monaco-kusto/release/esm/kusto.worker.js`
```

在 KustoLanguageService-loader.js 文件中，添加以下自定义加载程序。它取代了配置文件中 importScripts 的使用：

module.exports = function loader(source) {
    source = `var Kusto = require("@kusto/language-service-next/Kusto.Language.Bridge.min");\n${source}`;

    return source.replace(/importScripts.*/g,'');;
}

在你的应用中，添加以下代码：

在 window 对象上定义 MonacoEnvironment 函数。将 <path_and_full_name_of_kusto_worker> 替换为前面记录的工作器路径。
```
window.MonacoEnvironment = { globalAPI: true, getWorkerUrl: function() { return "<path_and_full_name_of_kusto_worker>"} };
```

从 HTML 元素创建 monaco.editor 对象：

this.editor = monaco.editor.create(editorElement, editorConfig)

调用 monaco.contribution API 以注册 Kusto 语言：

import('monaco.contribution').then(async (contribution: any) => {
    const model = this.monaco && this.monaco.editor.createModel("", 'kusto');
    this.editor.setModel(model);
    const workerAccessor: monaco.languages.kusto.WorkerAccessor = await monaco.languages.kusto.getKustoWorker();
    const worker: monaco.languages.kusto.KustoWorker = await workerAccessor(model.uri);
})

将数据库架构添加到编辑器

monaco-kusto 包提供了一种将数据库架构添加到编辑器的方法。该架构使编辑器能够提供自动完成建议和其他功能。

使用以下结构可定义架构：

const schema = {... <YOUR_DATABASE_SCHEMA> ...};

export function setSchema(editor) {
  window.monaco.languages.kusto.getKustoWorker().then((workerAccessor) => {
    const model = editor.getModel();
    workerAccessor(model.uri).then((worker) => {
      //EITHER: Set schema from a show schema command
      // worker.setSchemaFromShowSchema(
      //     schema,
      //     clusterURI,
      //     database
      // );
      //OR: Set schema from a manually created schema
      // worker.setSchema(schema);
    });
  });
}

可以使用以下方法之一获取数据库架构：

从查询环境
手动创建

在查询环境中，选择要创建架构的数据库。
在查询窗口中，运行以下查询：
```
.show schema as json
```
复制查询结果并将其粘贴为 schema 常量。查询的结果是数据库列表（请参阅 schema.ts 文件中的接口 Result）。
使用 setSchemaFromShowSchema() 方法在编辑器中设置架构。还必须指定要在编辑器中使用的数据库 URI 和名称。

创建包含数据库架构的架构对象。有关详细信息，请参阅 src/schema.ts 文件中的 clusterType 接口。以下示例演示包含单个数据库和单个表的架构对象：

{
  "clusterType":"Engine",
  "cluster":{
    "connectionString":"<CONNECTION_STRING>",
    "databases":[ {
      "database": {
        "name": "<DATABASE_NAME>",
        "majorVersion": 5,
        "minorVersion": 0,
        "tables": [ {
          "name": "<TABLE_NAME>",
          "entityType": "Table",
          "columns": [ {
            "name": "<COLUMN_NAME>",
            "type": "<COLUMN_TYPE>"
          }, ... ]
        }, ... ]
      }
    }, ... ]
  },
  // Defines schema for the required database.
  // The schema must also be defined in the cluster object.
  "database": {
    "name": "<DATABASE_NAME>",
    "majorVersion": 5,
    "minorVersion": 0,
    "tables": [ {
      "name": "<TABLE_NAME>",
      "entityType": "Table",
      "columns": [ {
        "name": "<COLUMN_NAME>",
        "type": "<COLUMN_TYPE>"
      }, ... ]
    }, ... ]
  }
}

使用 setSchema() 方法在编辑器中设置架构。

示例项目

可以找到使用 monaco-kusto 包的示例项目。若要使用示例，请克隆 monaco-kusto GitHub 存储库。示例位于 samples/react 文件夹中。

设置并测试示例项目

从克隆的存储库的根目录运行以下命令：

安装依赖项并生成项目：
```
npm install
```
验证项目是否正常工作。如果成功，index.html 将打开。
```
npm run watch
```

通过