Add sqlproj property to trace the origin of the project. (#18670)

* Add sqlproj property to trace the origin of the project.

As part of the database migration process (schema conversion, in particular) we want to be able to tell when converted schemas are being built/deployed to the actual database server. Given that we rely on the SQL Database Projects ADS extension for the compilation/deployment, we don't have too many options other than updating the said extension.

The suggested approach is to make the following changes:
1) Add new property to the sqlproj file (called `DatabaseSource`), which will maintain the origin(s) of the project. The property can contain multiple values (separated by semicolon), in case same project contains objects produced by multiple sources (extract schema, convert from another database, etc.).
2) During build and deploy actions, send the well-known values from the newly added property to the telemetry. We don't want to send any random value of the property, as it may raise some privacy concerns. Instead we define a list of the well-known values that we know do not carry any personal information and send those, if they are specified.

This change adds all necessary APIs to the SQl Database projects extension which will be consumed by our migration extensions to populate new `DatabaseSource` property.

* Use `undefined` instead of `null`

Co-authored-by: Kim Santiago <kisantia@microsoft.com>

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

@@ -332,7 +332,8 @@ export function fileAlreadyExists(filename: string) { return localize('fileAlrea
 export function folderAlreadyExists(filename: string) { return localize('folderAlreadyExists', "A folder with the name '{0}' already exists on disk at this location. Please choose another name.", filename); }
 export function folderAlreadyExistsChooseNewLocation(filename: string) { return localize('folderAlreadyExistsChooseNewLocation', "A folder with the name '{0}' already exists on disk at this location. Please choose another location.", filename); }
 export function invalidInput(input: string) { return localize('invalidInput', "Invalid input: {0}", input); }
-export function invalidProjectPropertyValue(propertyName: string) { return localize('invalidPropertyValue', "Invalid value specified for the property '{0}' in .sqlproj file", propertyName); }
+export function invalidProjectPropertyValueInSqlProj(propertyName: string) { return localize('invalidPropertyValueInSqlProj', "Invalid value specified for the property '{0}' in .sqlproj file", propertyName); }
+export function invalidProjectPropertyValueProvided(propertyName: string) { return localize('invalidPropertyValueProvided', "Project property value '{0} is invalid", propertyName); }
 export function unableToCreatePublishConnection(input: string) { return localize('unableToCreatePublishConnection', "Unable to construct connection: {0}", input); }
 export function circularProjectReference(project1: string, project2: string) { return localize('cicularProjectReference', "Circular reference from project {0} to project {1}", project1, project2); }
 export function errorFindingBuildFilesLocation(err: any) { return localize('errorFindingBuildFilesLocation', "Error finding build files location: {0}", utils.getErrorMessage(err)); }
@@ -423,6 +424,7 @@ export const PropertyGroup = 'PropertyGroup';
 export const Type = 'Type';
 export const ExternalStreamingJob: string = 'ExternalStreamingJob';
 export const Sdk: string = 'Sdk';
+export const DatabaseSource = 'DatabaseSource';
 
 export const BuildElements = localize('buildElements', "Build Elements");
 export const FolderElements = localize('folderElements', "Folder Elements");
@@ -440,6 +442,14 @@ export const DefaultCollationProperty = 'DefaultCollation';
 /** Default database collation to use when none is specified in the project */
 export const DefaultCollation = 'SQL_Latin1_General_CP1_CI_AS';
 
+/**
+ * Well-known database source values that are allowed to be sent in telemetry.
+ *
+ * 'dsct-oracle-to-ms-sql' is the name of an extension which allows users to migrate from Oracle to Microsoft SQL platform.
+ * When looking at telemetry, we would like to know if a built or deployed database originated from the DSCT extension.
+ */
+export const WellKnownDatabaseSources = ['dsct-oracle-to-ms-sql'];
+
 // SqlProj File targets
 export const NetCoreTargets = '$(NETCoreTargetsPath)\\Microsoft.Data.Tools.Schema.SqlTasks.targets';
 export const SqlDbTargets = '$(SQLDBExtensionsRefPath)\\Microsoft.Data.Tools.Schema.SqlTasks.targets';

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

@@ -599,3 +599,33 @@ export function getFoldersAlongPath(startFolder: string, endFolder: string): str
 
 	return folders;
 }
+
+/**
+ * Determines whether provided value is a well-known database source and therefore is allowed to be sent in telemetry.
+ *
+ * @param value Value to check if it is a well-known database source
+ * @returns Normalized database source value if it is well-known, otherwise returns undefined
+ */
+export function getWellKnownDatabaseSource(value: string): string | undefined {
+	const upperCaseValue = value.toUpperCase();
+	return constants.WellKnownDatabaseSources
+		.find(wellKnownSource => wellKnownSource.toUpperCase() === upperCaseValue);
+}
+
+/**
+ * Filters an array of specified database project sources to only those that are well-known.
+ *
+ * @param databaseSourceValues Array of database source values to filter
+ * @returns Array of well-known database sources
+ */
+export function getWellKnownDatabaseSources(databaseSourceValues: string[]): string[] {
+	const databaseSourceSet = new Set<string>();
+	for (let databaseSourceValue of databaseSourceValues) {
+		const wellKnownDatabaseSourceValue = getWellKnownDatabaseSource(databaseSourceValue);
+		if (wellKnownDatabaseSourceValue) {
+			databaseSourceSet.add(wellKnownDatabaseSourceValue);
+		}
+	}
+
+	return Array.from(databaseSourceSet);
+}