Clean up docs for connect and ConnectionResult (#19509)

* Clean up docs for connect and ConnectionResult

* links

* fix build

* fix

extensions/arc/src/models/miaaModel.ts

@@ -187,7 +187,7 @@ export class MiaaModel extends ResourceModel {
 			if (!result.connected) {
 				throw new Error(result.errorMessage);
 			}
-			this._activeConnectionId = result.connectionId;
+			this._activeConnectionId = result.connectionId!;
 		}
 
 		const provider = azdata.dataprotocol.getProvider<azdata.MetadataProvider>(this._connectionProfile!.providerName, azdata.DataProviderType.MetadataProvider);

extensions/arc/src/models/postgresModel.ts

@@ -148,7 +148,7 @@ export class PostgresModel extends ResourceModel {
 				if (!result.connected) {
 					throw new Error(result.errorMessage);
 				}
-				this._activeConnectionId = result.connectionId;
+				this._activeConnectionId = result.connectionId!;
 			}
 
 			// TODO Need to make separate calls for worker nodes and coordinator node

extensions/arc/src/ui/dialogs/connectSqlDialog.ts

@@ -111,7 +111,7 @@ export abstract class ConnectToSqlDialog extends InitializingComponent {
 		};
 		const result = await azdata.connection.connect(connectionProfile, false, false);
 		if (result.connected) {
-			connectionProfile.id = result.connectionId;
+			connectionProfile.id = result.connectionId!;
 			const credentialProvider = await azdata.credentials.getProvider(credentialNamespace);
 			if (connectionProfile.savePassword) {
 				await credentialProvider.saveCredential(createCredentialId(this._controllerModel.info.id, this._model.info.resourceType, this._model.info.name), connectionProfile.password);

extensions/sql-database-projects/src/common/utils.ts

@@ -685,3 +685,9 @@ export function findSqlVersionInTargetPlatform(targetPlatform: string): number |
 	}
 	return undefined;
 }
+
+export function throwIfNotConnected(connectionResult: azdataType.ConnectionResult): void {
+	if (!connectionResult.connected) {
+		throw new Error(`${connectionResult.errorMessage} (${connectionResult.errorCode})`);
+	}
+}

extensions/sql-database-projects/src/dialogs/publishDatabaseDialog.ts

@@ -194,7 +194,9 @@ export class PublishDatabaseDialog {
 				const connProfile: azdataType.IConnectionProfile = dataSource.getConnectionProfile();
 
 				if (dataSource.integratedSecurity) {
-					connId = (await utils.getAzdataApi()!.connection.connect(connProfile, false, false)).connectionId;
+					const connResult = await utils.getAzdataApi()!.connection.connect(connProfile, false, false);
+					utils.throwIfNotConnected(connResult);
+					connId = connResult.connectionId!;
 				}
 				else {
 					connId = (await utils.getAzdataApi()!.connection.openConnectionDialog(undefined, connProfile)).connectionId;
@@ -207,7 +209,6 @@ export class PublishDatabaseDialog {
 
 				connId = this.connectionId;
 			}
-
 			return await utils.getAzdataApi()!.connection.getUriForConnection(connId);
 		}
 		catch (err) {

extensions/sql-database-projects/src/models/deploy/deployService.ts

@@ -333,7 +333,7 @@ export class DeployService {
 			const connectionResult = <ConnectionResult>connection;
 			if (connectionResult) {
 				const connected = connectionResult !== undefined && connectionResult.connected && connectionResult.connectionId !== undefined;
-				return { validated: connected, errorMessage: connected ? '' : constants.connectionFailedError(connectionResult?.errorMessage) };
+				return { validated: connected, errorMessage: connected ? '' : constants.connectionFailedError(connectionResult?.errorMessage!) };
 			} else {
 				return { validated: false, errorMessage: constants.connectionFailedError('') };
 			}
@@ -346,7 +346,7 @@ export class DeployService {
 	private async formatConnectionResult(connection: ConnectionResult | string | undefined): Promise<string> {
 		const getAzdataApi = await utils.getAzdataApi();
 		const connectionResult = connection !== undefined && getAzdataApi ? <ConnectionResult>connection : undefined;
-		return connectionResult ? connectionResult.connectionId : <string>connection;
+		return connectionResult?.connected ? connectionResult.connectionId! : <string>connection;
 	}
 
 	public async getConnection(profile: ISqlConnectionProperties, saveConnectionAndPassword: boolean, database: string): Promise<string | undefined> {
@@ -364,7 +364,8 @@ export class DeployService {
 		if (connection) {
 			const connectionResult = <ConnectionResult>connection;
 			if (getAzdataApi) {
-				return await getAzdataApi.connection.getUriForConnection(connectionResult.connectionId);
+				utils.throwIfNotConnected(connectionResult);
+				return getAzdataApi.connection.getUriForConnection(connectionResult.connectionId!);
 			} else {
 				return <string>connection;
 			}

extensions/sql-database-projects/src/models/publishProfile/publishProfile.ts

@@ -80,8 +80,9 @@ async function readConnectionString(xmlDoc: any): Promise<{ connectionId: string
 			const azdataApi = utils.getAzdataApi();
 			if (dataSource.integratedSecurity) {
 				if (azdataApi) {
-					const connection = await utils.getAzdataApi()!.connection.connect(connectionProfile, false, false);
-					connId = connection.connectionId;
+					const connectionResult = await utils.getAzdataApi()!.connection.connect(connectionProfile, false, false);
+					utils.throwIfNotConnected(connectionResult);
+					connId = connectionResult.connectionId!;
 				} else {
 					// TODO@chgagnon - hook up VS Code MSSQL
 				}

src/sql/azdata.d.ts

@@ -190,8 +190,10 @@ declare module 'azdata' {
 			connectionCompletionOptions?: IConnectionCompletionOptions): Thenable<Connection>;
 
 		/**
-		 * Opens the connection and add it to object explorer and opens the dashboard and returns the ConnectionResult
-		 * @param connectionProfile connection profile
+		 * Attempts to open a new connection with the options from the given connection profile.
+		 * @param connectionProfile The {@link IConnectionProfile} containing the information for the connection
+		 * @param saveConnection Whether to save the connection in the saved connections list of the Servers view. Default is true
+		 * @param showDashboard Whether to show the dashboard for the connection upon success. Default is true
 		 */
 		export function connect(connectionProfile: IConnectionProfile, saveConnection?: boolean, showDashboard?: boolean): Thenable<ConnectionResult>;
 
@@ -5242,10 +5244,28 @@ declare module 'azdata' {
 	}
 
 	export interface ConnectionResult {
+		/**
+		 * Whether the connection was successful
+		 */
 		connected: boolean;
-		connectionId: string;
-		errorMessage: string;
-		errorCode: number;
+		/**
+		 * The ID of the connection if it was successful. {@link connection.getUriForConnection} can be used to get
+		 * the URI for this connection used by many of the other Extension API functions.
+		 */
+		connectionId?: string | undefined;
+		/**
+		 * The error message if the connection was unsuccessful
+		 *
+		 * e.g. Login failed for user '<user>'.
+		 */
+		errorMessage?: string | undefined;
+		/**
+		 * The error code number associated with the error if the connection was unsuccessful.
+		 *
+		 * e.g. 18456
+		 * (https://docs.microsoft.com/sql/relational-databases/errors-events/mssqlserver-18456-database-engine-error)
+		 */
+		errorCode?: number | undefined;
 	}
 
 	export namespace nb {