Skip to content

Commit 5adba0d

Browse files
HeidiSteenHeidiSteen
committed
Merge branch 'release-sqlseattle' of https://github.com/MicrosoftDocs/sql-docs-pr into heidist-ctp2-eula
2 parents d590644 + 8296e02 commit 5adba0d

10 files changed

Lines changed: 557 additions & 9 deletions

File tree

‎docs/azure-data-studio/extensibility-apis.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Extensibility APIs for Azure Data Studio (preview) | Microsoft Docs
3+
description: Extensibility APIs for Azure Data Studio (preview)
4+
ms.custom: "tools|sos"
5+
ms.date: "09/24/2018"
6+
ms.reviewer: "alayu; sstein"
7+
ms.prod: sql
8+
ms.suite: "sql"
9+
ms.prod_service: sql-tools
10+
ms.component: sos
11+
ms.tgt_pltfrm: ""
12+
ms.topic: conceptual
13+
author: "stevestein"
14+
ms.author: "sstein"
15+
manager: craigg
16+
---
17+
# Azure Data Studio extensibility APIs
18+
19+
[!INCLUDE[name-sos](../includes/name-sos.md)] provides an API that extensions can use to interact with other parts of the application, such as Object Explorer. These APIs are available from the [`src/sql/sqlops.d.ts`](https://github.com/Microsoft/sqlopsstudio/blob/master/src/sql/sqlops.d.ts) file and are described below.
20+
21+
## Connection Management
22+
`sqlops.connection`
23+
24+
_Available starting in version 0.26.7 (February Public Preview)_
25+
26+
### Top-level Functions
27+
28+
- `getCurrentConnection(): Thenable<sqlops.connection.Connection>`
29+
Gets the current connection based on the active editor or Object Explorer selection.
30+
31+
- `getActiveConnections(): Thenable<sqlops.connection.Connection[]>`
32+
Gets a list of all the user's connections that are active. Returns an empty list if there are no such connections.
33+
34+
- `getCredentials(connectionId: string): Thenable<{ [name: string]: string }>`
35+
Gets a dictionary containing the credentials associated with a connection. These would otherwise be returned as part of the options dictionary under a `sqlops.connection.Connection` object but get stripped from that object.
36+
37+
### `Connection`
38+
- `options: { [name: string]: string }` The dictionary of connection options
39+
- `providerName: string` The name of the connection provider (e.g. "MSSQL")
40+
- `connectionId: string` The unique identifier for the connection
41+
42+
### Example Code
43+
```
44+
> let connection = sqlops.connection.getCurrentConnection();
45+
connection: {
46+
providerName: ‘MSSQL’,
47+
connectionId: ‘d97bb63a-466e-4ef0-ab6f-00cd44721dcc’,
48+
options: {
49+
server: ‘mairvine-sql-server’,
50+
user: ‘sa’,
51+
authenticationType: ‘sqlLogin’,
52+
…
53+
},
54+
…
55+
}
56+
> let credentials = sqlops.connection.getCredentials(connection.connectionId);
57+
credentials: {
58+
password: ‘abc123’
59+
}
60+
61+
```
62+
63+
## Object Explorer
64+
65+
`sqlops.objectexplorer`
66+
67+
_Available starting in version 0.27.3 (March Public Preview)_
68+
69+
### Top-level Functions
70+
- `getNode(connectionId: string, nodePath?: string): Thenable<sqlops.objectexplorer.ObjectExplorerNode>`
71+
Get an Object Explorer node corresponding to the given connection and path. If no path is given, it returns the top-level node for the given connection. If there is no node at the given path, it returns `undefined`. Note: The `nodePath` for an object is generated by the SQL Tools Service backend and is difficult to construct by hand. Future API improvements will allow you to get nodes based on metadata you provide about the node, such as name, type and schema.
72+
73+
- `getActiveConnectionNodes(): Thenable<sqlops.objectexplorer.ObjectExplorerNode>`
74+
Get all active Object Explorer connection nodes.
75+
76+
- `findNodes(connectionId: string, type: string, schema: string, name: string, database: string, parentObjectNames: string[]): Thenable<sqlops.objectexplorer.ObjectExplorerNode[]>`
77+
Find all Object Explorer nodes that match the given metadata. The `schema`, `database`, and `parentObjectNames` arguments should be `undefined` when they are not applicable. `parentObjectNames` is a list of non-database parent objects, from highest to lowest level in Object Explorer, that the desired object is under. For example, when searching for a column "column1" that belongs to a table "schema1.table1" and database "database1" with connection ID `connectionId`, call `findNodes(connectionId, 'Column', undefined, 'column1', 'database1', ['schema1.table1'])`. Also see the [list of types that SQL Operations Studio supports by default](https://github.com/Microsoft/sqlopsstudio/wiki/Object-Explorer-types-supported-by-FindNodes-API) for this API call.
78+
79+
### ObjectExplorerNode
80+
- `connectionId: string`
81+
The id of the connection that the node exists under
82+
83+
- `nodePath: string`
84+
The path of the node, as used for a call to the `getNode` function.
85+
86+
- `nodeType: string`
87+
A string representing the type of the node
88+
89+
- `nodeSubType: string`
90+
A string representing the subtype of the node
91+
92+
- `nodeStatus: string`
93+
A string representing the status of the node
94+
95+
- `label: string`
96+
The label for the node as it appears in Object Explorer
97+
98+
- `isLeaf: boolean`
99+
Whether the node is a leaf node and therefore has no children
100+
101+
- `metadata: sqlops.ObjectMetadata`
102+
Metadata describing the object represented by this node
103+
104+
- `errorMessage: string`
105+
Message shown if the node is in an error state
106+
107+
- `isExpanded(): Thenable<boolean>`
108+
Whether the node is currently expanded in Object Explorer
109+
110+
- `setExpandedState(expandedState: vscode.TreeItemCollapsibleState): Thenable<void>`
111+
Set whether the node is expanded or collapsed. If the state is set to None, the node will not be changed.
112+
113+
- `setSelected(selected: boolean, clearOtherSelections?: boolean): Thenable<void>`
114+
Set whether the node is selected. If `clearOtherSelections` is true, clear any other selections when making the new selection. If it is false, leave any existing selections. `clearOtherSelections` defaults to true when `selected` is true and false when `selected` is false.
115+
116+
- `getChildren(): Thenable<sqlops.objectexplorer.ObjectExplorerNode[]>`
117+
Get all the child nodes of this node. Returns an empty list if there are no children.
118+
119+
- `getParent(): Thenable<sqlops.objectexplorer.ObjectExplorerNode>`
120+
Get the parent node of this node. Returns undefined if there is no parent.
121+
122+
### Example Code
123+
124+
```cs
125+
private async interactWithOENode(selectedNode: sqlops.objectexplorer.ObjectExplorerNode): Promise<void> {
126+
let choices = ['Expand', 'Collapse', 'Select', 'Select (multi)', 'Deselect', 'Deselect (multi)'];
127+
if (selectedNode.isLeaf) {
128+
choices[0] += ' (is leaf)';
129+
choices[1] += ' (is leaf)';
130+
} else {
131+
let expanded = await selectedNode.isExpanded();
132+
if (expanded) {
133+
choices[0] += ' (is expanded)';
134+
} else {
135+
choices[1] += ' (is collapsed)';
136+
}
137+
}
138+
let parent = await selectedNode.getParent();
139+
if (parent) {
140+
choices.push('Get Parent');
141+
}
142+
let children = await selectedNode.getChildren();
143+
children.forEach(child => choices.push(child.label));
144+
let choice = await vscode.window.showQuickPick(choices);
145+
let nextNode: sqlops.objectexplorer.ObjectExplorerNode = undefined;
146+
if (choice === choices[0]) {
147+
selectedNode.setExpandedState(vscode.TreeItemCollapsibleState.Expanded);
148+
} else if (choice === choices[1]) {
149+
selectedNode.setExpandedState(vscode.TreeItemCollapsibleState.Collapsed);
150+
} else if (choice === choices[2]) {
151+
selectedNode.setSelected(true);
152+
} else if (choice === choices[3]) {
153+
selectedNode.setSelected(true, false);
154+
} else if (choice === choices[4]) {
155+
selectedNode.setSelected(false);
156+
} else if (choice === choices[5]) {
157+
selectedNode.setSelected(false, true);
158+
} else if (choice === 'Get Parent') {
159+
nextNode = parent;
160+
} else {
161+
let childNode = children.find(child => child.label === choice);
162+
nextNode = childNode;
163+
}
164+
if (nextNode) {
165+
let updatedNode = await sqlops.objectexplorer.getNode(nextNode.connectionId, nextNode.nodePath);
166+
this.interactWithOENode(updatedNode);
167+
}
168+
}
169+
170+
vscode.commands.registerCommand('mssql.objectexplorer.interact', () => {
171+
sqlops.objectexplorer.getActiveConnectionNodes().then(activeConnections => {
172+
vscode.window.showQuickPick(activeConnections.map(connection => connection.label + ' ' + connection.connectionId)).then(selection => {
173+
let selectedNode = activeConnections.find(connection => connection.label + ' ' + connection.connectionId === selection);
174+
this.interactWithOENode(selectedNode);
175+
});
176+
});
177+
});
178+
```
179+
180+
## Proposed APIs
181+
182+
We have added proposed APIs to allow extensions to display custom UI in dialogs, wizards, and document tabs, among other capabilities. See the [proposed API types file](https://github.com/Microsoft/sqlopsstudio/blob/master/src/sql/sqlops.proposed.d.ts) for more documentation, though be aware that these APIs are subject to change at any time. Examples of how to use some of these APIs can be found in the ["sqlservices" sample extension](https://github.com/Microsoft/sqlopsstudio/tree/master/samples/sqlservices).
183+
184+

0 commit comments

Comments
 (0)