Building and Contributing - MarkMpn/Sql4Cds GitHub Wiki

One great way to contribute to SQL 4 CDS is reporting issues. If a query fails to run, is giving incorrect results, or is running much slower than you'd expect please create an issue and include the full text of the query.

It's often much easier to figure out what's going wrong if you can produce a sample query that has the same error using standard tables such as account and contact so I don't have to figure out the schema of your custom tables that might be contributing to the error.

If you're getting incorrect results or poor performance, it can also be helpful if you include a screenshot of the execution plan that SQL 4 CDS has generated.

Clone the repo and open the main solution in Visual Studio. Ensure the MarkMpn.Sql4Cds project is set as the startup project. Edit the Debug properties of this project:

• Start external program: select the full path to your XrmToolBox.exe instance
• Command line arguments: (optional) get XrmToolBox to connect to an instance and open SQL 4 CDS using /connection:"<connection name>" /plugin:"SQL 4 CDS"
• Working directory: select the folder containing XrmToolBox.exe

If you have changed the plugin folder that XrmToolBox uses, update the post-build events for the following projects accordingly:

• MarkMpn.Sql4Cds
• MarkMpn.Sql4Cds.Controls
• MarkMpn.Sql4Cds.Engine.NetFx
• MarkMpn.Sql4Cds.XTB

With these changes made, you should be able to run the project and start debugging.

The majority of the XrmToolBox tool user interface code is in the MarkMpn.Sql4Cds.XTB project.

The Azure Data Studio extension is in two parts. The first is the extension itself, built in TypeScript and is stored in the AzureDataStudioExtension folder. The package.json file defines the configuration settings for the extension and the features that it provides to Azure Data Studio - the dashboard and connection provider. The main.ts file is the entry point for the extension - the activate starts up the language server and defines the notifications from the server that it will handle.

To build the extension, first install the dependencies with:

npm i -g vsce
yarn install

Open the AzureDataStudioExtension folder in VS Code and press F5 to start debugging.

The second part is the language server. This is built using .NET and implements the actual SQL functionality, interacting with the user interface via a JSON RPC connection. The code for this is in the MarkMpn.Sql4Cds.LanguageServer project in the main solution and is built with Visual Studio.

After cloning the repo & building the solution, open Azure Data Studio and go to the settings for the SQL 4 CDS extension. Set the SQL4CDS.debugSourcePath setting to the folder containing your debug build (e.g. "C:\Users\username...\MarkMpn.Sql4Cds.LanguageServer\bin\debug\net7.0") and set the SQL4CDS.useDebugSource setting to true. When you restart Azure Data Studio it will now load your debug build of the language server to which you can attach a debugger. The process name to attach to will be simply "dotnet.exe"

The core logic for the SSMS plugin is in the MarkMpn.Sql4Cds.SSMS shared project. Separate projects for SSMS 18 and 19 then reference that project with different build options.

Run Visual Studio as Administrator and build either MarkMpn.Sql4Cds.SSMS.18 or MarkMpn.Sql4Cds.SSMS.19 as appropriate, then start SSMS. The plugin will be loaded automatically. Attach the Visual Studio debugger to the Ssms.exe process to start debugging.

The same core engine is used across the XrmToolBox, Azure Data Studio and SSMS plugins. This code is in the MarkMpn.Sql4Cds.Engine solution.

If you would like to contribute any features at this level, please ensure they are covered by tests in the MarkMpn.Sql4Cds.Engine.Tests project as well. All behaviour should be as close as possible to that of SQL Server. If a language feature is only partially implemented, the logic should check for any attempted use of the unsupported areas and throw an exception so the user is aware that the feature they are trying to use is not supported instead of silently ignoring them.

Care generally needs to be taken around type conversions, which should use the features of the SqlTypeConverter class for consistency, and null value handling.

Error messages should follow those used by SQL Server and should include a reference to the fragment of the query that caused it to allow for highlighting of the problem.

Any new functions should be exposed via Intellisense using the Autocomplete classes in both the MarkMpn.Sql4Cds.XTB and MarkMpn.Sql4Cds.LanguageServer projects.

If a new execution plan node or properties are introduced, thought needs to be given to the appearance of it in the execution plan view. This includes the associated text & icon for nodes, and display name and description for properties. Icons are handled differently in Azure Data Studio. Again, these should be as consistent as possible with SQL Server.