Add support for XEvent logging and bump API version to v3

extension-host/include/sqlextensionhostcallbacks.h

@@ -0,0 +1,79 @@
+//*********************************************************************
+//      Copyright (c) Microsoft Corporation.
+//
+// Host callbacks protocol between the host and extensions.
+// Optional API surface introduced alongside v3 of the Extension API.
+//
+// @File: sqlextensionhostcallbacks.h
+//
+//*********************************************************************
+
+#ifndef __SQLEXTENSIONHOSTCALLBACKS
+#define __SQLEXTENSIONHOSTCALLBACKS
+
+#include "sqlexternallanguage.h"
+#include "sqlextensiontracelevel.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+// Callback function provided by the host for logging XEvents from Extension.
+//
+typedef void (*PFunc_ExtensionLogXEvent)(
+	const SQLCHAR	*ExtensionName,
+	SQLULEN		ExtensionNameLength,
+	SQLGUID		SessionId,
+	SQLUSMALLINT	TaskId,
+	SQLUSMALLINT	TraceLevel,
+	SQLINTEGER	ErrorCode,
+	const SQLCHAR	*Message,
+	SQLULEN		MessageLength
+	);
+
+// Host callbacks structure passed from host to Extension.
+//
+#define SQLEXTENSION_HOST_CALLBACKS_VERSION_1 1
+#define SQLEXTENSION_HOST_CALLBACKS_MIN_SUPPORTED_VERSION SQLEXTENSION_HOST_CALLBACKS_VERSION_1
+
+typedef struct _SQLEXTENSION_HOST_CALLBACKS
+{
+	// Highest SQLEXTENSION_HOST_CALLBACKS_VERSION_* the host populates.
+	// Extension must validate before reading version-gated fields.
+	//
+	SQLUSMALLINT Version;
+
+	// Explicit padding so SizeInBytes is naturally 4-byte aligned regardless
+	// of compiler packing settings. Must be zero.
+	//
+	SQLUSMALLINT Reserved0;
+
+	// sizeof(SQLEXTENSION_HOST_CALLBACKS) as the host saw it at build time.
+	// Extension must validate this is greater or equal the size of every field it intends
+	// to read. Lets a newer Extension safely run against an older host that supplied a smaller struct.
+	//
+	SQLUINTEGER SizeInBytes;
+
+	// Version 1 callbacks.
+	//
+	PFunc_ExtensionLogXEvent LogXEvent;
+
+	// Reserved for future expansion. Zero-initialized by the host. Extension must not read or call these.
+	//
+	void *Reserved1;
+	void *Reserved2;
+} SQLEXTENSION_HOST_CALLBACKS;
+
+// Optional API (v3+)
+// Receives host callback functions from the host.
+//
+SQLEXTENSION_INTERFACE
+SQLRETURN SetHostCallbacks(
+	SQLEXTENSION_HOST_CALLBACKS *Callbacks
+	);
+
+#ifdef __cplusplus
+} /* End of extern "C" { */
+#endif/* __cplusplus */
+
+#endif/* __SQLEXTENSIONHOSTCALLBACKS */

extension-host/include/sqlextensiontracelevel.h

@@ -0,0 +1,26 @@
+//*********************************************************************
+//      Copyright (c) Microsoft Corporation.
+//
+// ExtensionTraceLevel enum shared between the host and extensions.
+//
+// @File: sqlextensiontracelevel.h
+//
+//*********************************************************************
+
+#ifndef __SQLEXTENSIONTRACELEVEL
+#define __SQLEXTENSIONTRACELEVEL
+
+// Trace levels for events logged via the LogXEvent host callback.
+// Lowest numeric value is the most severe, matching the Windows ETW
+// TRACE_LEVEL_* convention.
+//
+enum ExtensionTraceLevel
+{
+	Extension_Critical    = 1,
+	Extension_Error       = 2,
+	Extension_Warning     = 3,
+	Extension_Information = 4,
+	Extension_Verbose     = 5
+};
+
+#endif /* __SQLEXTENSIONTRACELEVEL */

extension-host/include/sqlexternallanguage.h

@@ -28,7 +28,7 @@
 extern "C" {
 #endif /* __cplusplus */
 
-#define EXTERNAL_LANGUAGE_EXTENSION_API 2
+#define EXTERNAL_LANGUAGE_EXTENSION_API 3
 
 SQLEXTENSION_INTERFACE
 SQLUSMALLINT GetInterfaceVersion();

language-extensions/dotnet-core-CSharp/include/nativecsharpextension.h

@@ -24,6 +24,7 @@
 #include <sql.h>
 #include "sqlexternallanguage.h"
 #include "sqlexternallibrary.h"
+#include "sqlextensionhostcallbacks.h"
 #include "DotnetEnvironment.h"
 
 //  Returns the string with the address of the first character and length
@@ -142,6 +143,17 @@ SQLEXTENSION_INTERFACE SQLRETURN CleanupSession(SQLGUID sessionId, SQLUSMALLINT
 //
 SQLEXTENSION_INTERFACE SQLRETURN Cleanup();
 
-//  Dotnet environment pointer
+//  Receives host callback function pointers from the host.
+//  Optional API, supported since v3 of the Extension API.
 //
-static DotnetEnvironment* g_dotnet_runtime = nullptr;
+SQLEXTENSION_INTERFACE SQLRETURN SetHostCallbacks(
+    SQLEXTENSION_HOST_CALLBACKS *hostCallbacks);
+
+//  Dotnet environment pointer. Defined in nativecsharpextension.cpp.
+//
+extern DotnetEnvironment* g_dotnet_runtime;
+
+//  Host callbacks pointer provided by the host via SetHostCallbacks.
+//  Defined in nativecsharpextension.cpp.
+//
+extern SQLEXTENSION_HOST_CALLBACKS* g_hostCallbacks;

language-extensions/dotnet-core-CSharp/src/managed/CSharpExtension.cs

@@ -601,6 +601,127 @@ public static short GetOutputParam(
             });
         }
 
+        /// <summary>
+        /// Delegate type matching the host's LogXEvent callback signature.
+        /// </summary>
+        [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
+        public delegate void LogXEventCallbackDelegate(
+            byte   *extensionName,
+            ulong  extensionNameLength,
+            Guid   sessionId,
+            ushort taskId,
+            ushort traceLevel,
+            int    errorCode,
+            byte   *message,
+            ulong  messageLength);
+
+        /// <summary>
+        /// Managed representation of the SQLEXTENSION_HOST_CALLBACKS structure.
+        /// Must match the native struct layout exactly.
+        /// </summary>
+        [StructLayout(LayoutKind.Sequential)]
+        public struct SqlExtensionHostCallbacks
+        {
+            // Highest SQLEXTENSION_HOST_CALLBACKS_VERSION_* the host populates.
+            // Extension must validate before reading version-gated fields.
+            //
+            public ushort Version;
+
+            // Explicit padding so SizeInBytes is naturally 4-byte aligned regardless
+            // of compiler packing settings. Must be zero.
+            //
+            public ushort Reserved0;
+
+            // sizeof(SQLEXTENSION_HOST_CALLBACKS) as the host saw it at build time.
+            // Extension must validate this is greater or equal the size of every field it intends
+            // to read. Lets a newer Extension safely run against an older host that supplied a smaller struct.
+            //
+            public uint SizeInBytes;
+
+            // Version 1 callbacks.
+            //
+            public IntPtr LogXEvent;
+
+            // Reserved for future expansion. Zero-initialized by the host. Extension must not read or call these.
+            //
+            public IntPtr Reserved1;
+            public IntPtr Reserved2;
+        }
+
+        /// <summary>
+        /// Minimal SQLEXTENSION_HOST_CALLBACKS version this extension understands.
+        /// If host callbacks version is greater than this, extension will still parse and read
+        /// known host callbacks and ignore unknown fields, allowing forward compatibility.
+        /// </summary>
+        /// 
+        private const ushort MinSupportedHostCallbacksVersion = 1;
+
+        /// <summary>
+        /// This delegate declares the delegate type of SetHostCallbacks.
+        /// </summary>
+        public delegate short SetHostCallbacksDelegate(
+            SqlExtensionHostCallbacks *hostCallbacks);
+
+        /// <summary>
+        /// This method implements SetHostCallbacks API.
+        /// Receives a pointer to the host callbacks structure, reads the callback
+        /// function pointers during this call, and stores any needed managed
+        /// delegates so managed code can call back into the host.
+        /// </summary>
+        /// <param name="hostCallbacks">
+        /// Pointer to the SQLEXTENSION_HOST_CALLBACKS structure provided by the host.
+        /// </param>
+        /// <returns>
+        /// SQL_SUCCESS(0), SQL_ERROR(-1)
+        /// </returns>
+        public static short SetHostCallbacks(
+            SqlExtensionHostCallbacks *hostCallbacks)
+        {
+            Logging.Trace("CSharpExtension::SetHostCallbacks");
+            return ExceptionUtils.WrapError(() =>
+            {
+                if (hostCallbacks == null)
+                {
+                    throw new ArgumentNullException(nameof(hostCallbacks));
+                }
+
+                // Validate the struct version before reading any version-gated fields.
+                //
+                if (hostCallbacks->Version < MinSupportedHostCallbacksVersion)
+                {
+                    Logging.Error(
+                        "CSharpExtension::SetHostCallbacks: unsupported host callbacks version: " +
+                        hostCallbacks->Version);
+
+                    throw new NotSupportedException(
+                        "Unsupported SQLEXTENSION_HOST_CALLBACKS version: " +
+                        hostCallbacks->Version);
+                }
+
+                if (hostCallbacks->LogXEvent != IntPtr.Zero)
+                {
+                    var logXEvent = Marshal.GetDelegateForFunctionPointer<LogXEventCallbackDelegate>(
+                        hostCallbacks->LogXEvent);
+                    Logging.SetLogXEventCallback(logXEvent);
+
+                    Logging.LogXEvent(
+                        extensionName: null,
+                        Guid.Empty,
+                        taskId: 0,
+                        traceLevel: Logging.TraceLevel.Information,
+                        errorCode: 0,
+                        "CSharp extension loaded, host callbacks registered (version " + hostCallbacks->Version + ")");
+                }
+                else
+                {
+                    // Host opted out of XEvent logging.
+                    // Clear any previously stored delegate.
+                    //
+                    Logging.SetLogXEventCallback(null);
+                }
+            });
+        }
+
         /// <summary>
         /// This delegate declares the delegate type of CleanupSession.
         /// </summary>