Feat/api compat validation

.github/workflows/build-and-test.yml

@@ -18,16 +18,36 @@ jobs:
         with:
           dotnet-version: 8.0.x
 
-      - name: Restore solution
+      - name: Restore projects
         run: dotnet restore projects/csharp/SqlRace.Examples.sln
         env:
           NUGET_AUTH_USERNAME: ${{ secrets.PACKAGES_USERNAME }}
           NUGET_AUTH_TOKEN: ${{ secrets.PACKAGES_PATTOKEN }}
 
-      - name: Build solution
+      - name: Build projects
         run: dotnet build projects/csharp/SqlRace.Examples.sln --no-restore --configuration Release
 
-      # NOTE: Tests are NOT executed in CI. Several tests initialise the SQL Race
-      # runtime via SqlRaceBootstrapper, which requires a SQL Race licence that the
-      # CI runner does not have (LicenceException). CI verifies compilation only;
-      # run `dotnet test` locally on a licenced machine to execute the test suite.
+      - name: Restore tests
+        run: dotnet restore tests/SqlRace.Examples.Tests/SqlRace.Examples.Tests.csproj
+        env:
+          NUGET_AUTH_USERNAME: ${{ secrets.PACKAGES_USERNAME }}
+          NUGET_AUTH_TOKEN: ${{ secrets.PACKAGES_PATTOKEN }}
+
+      - name: Build tests
+        run: dotnet build tests/SqlRace.Examples.Tests/SqlRace.Examples.Tests.csproj --no-restore --configuration Release
+
+      # NOTE: MOST tests are not executed in CI. Several of them initialise the SQL
+      # Race runtime via SqlRaceBootstrapper, which requires a SQL Race licence that
+      # the CI runner does not have (LicenceException). Run `dotnet test` locally on
+      # a licenced machine to execute the full suite, or scripts/run-examples-e2e.ps1
+      # for the runtime checks across C#, Python and MATLAB.
+      #
+      # The snippet compilation tests are the exception: they compile every snippet
+      # against the real SQL Race assemblies using Roslyn, which is a metadata-only
+      # operation needing no licence. They are the early warning that a new
+      # MESL.SQLRace.API release has broken the examples.
+      - name: Verify snippets compile against SQL Race
+        run: >
+          dotnet test tests/SqlRace.Examples.Tests/SqlRace.Examples.Tests.csproj
+          --no-build --configuration Release
+          --filter "FullyQualifiedName~SnippetCompilation"

Directory.Build.props

@@ -0,0 +1,26 @@
+<Project>
+
+  <PropertyGroup>
+    <!--
+      Which SQL Race build everything in this repo compiles and runs against.
+
+      "*" floats to the newest release on the feed, which is what everyday
+      development wants. A compatibility run overrides it to point at a
+      candidate before that candidate ships:
+
+        dotnet test  -p:SqlRaceApiVersion=<candidate-version>
+        ./scripts/run-examples-e2e.ps1 -SqlRaceApiVersion <candidate-version>
+
+      It is defined here rather than per-project because it has to apply to
+      every project at once. Overriding it on the test project alone leaves
+      SqlRace.Examples.Core and FunctionLibrary resolving whatever is published,
+      so the run would mix two different SQL Race builds and prove nothing.
+
+      Note that "*" only floats as far as the configured feed can see. An
+      offline restore settles on whatever is already in the local NuGet cache,
+      so pin explicitly when the answer matters.
+    -->
+    <SqlRaceApiVersion Condition="'$(SqlRaceApiVersion)' == ''">*</SqlRaceApiVersion>
+  </PropertyGroup>
+
+</Project>

projects/csharp/Directory.Build.props

@@ -1,5 +1,18 @@
 <Project>
 
+  <!--
+    MSBuild stops at the first Directory.Build.props it finds walking up from a
+    project, so without this import the repo-root one never reaches anything
+    under projects/csharp - and SqlRaceApiVersion is defined there.
+
+    Unimported, "$(SqlRaceApiVersion)" expands to nothing, and an empty version
+    range does not fail loudly: NuGet resolves the *oldest* MESL.SQLRace.API on
+    the feed. Every project here would then compile against a 2019 package while
+    the test project floats to the newest, which is precisely the mixed-build
+    situation SqlRaceApiVersion exists to prevent.
+  -->
+  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
+
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
     <Nullable>enable</Nullable>

projects/csharp/FunctionLibrary/FunctionLibrary.csproj

@@ -7,7 +7,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="MESL.SQLRace.API" Version="*" />
+    <PackageReference Include="MESL.SQLRace.API" Version="$(SqlRaceApiVersion)" />
     <PackageReference Include="System.ComponentModel.Composition" Version="8.*" />
   </ItemGroup>
 

projects/csharp/SqlRace.Examples.Core/ParameterBuilder.cs

@@ -194,7 +194,15 @@ public BuiltParameter Build()
     /// <param name="session">The session to add parameters to.</param>
     /// <param name="builders">The configured builders to build.</param>
     /// <returns>A list of created parameters.</returns>
-    public static IReadOnlyList<BuiltParameter> BuildBatch(Session session, IEnumerable<ParameterBuilder> builders)
+    /// <param name="configure">
+    /// Optional hook to add anything else - conversions, event definitions - to the same
+    /// configuration before it is committed. Only the first configuration set committed to a
+    /// session survives a reload, so anything that must persist has to go in this one.
+    /// </param>
+    public static IReadOnlyList<BuiltParameter> BuildBatch(
+        Session session,
+        IEnumerable<ParameterBuilder> builders,
+        Action<ConfigurationSet>? configure = null)
     {
         var config = session.CreateConfiguration();
         var parameters = new List<BuiltParameter>();
@@ -264,6 +272,8 @@ public static IReadOnlyList<BuiltParameter> BuildBatch(Session session, IEnumera
             parameters.Add(new BuiltParameter(parameter, (uint)channelId));
         }
 
+        configure?.Invoke(config);
+
         config.Commit();
         return parameters;
     }

projects/csharp/SqlRace.Examples.Core/SqlRace.Examples.Core.csproj

@@ -8,7 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="MESL.SQLRace.API" Version="*" />
+    <PackageReference Include="MESL.SQLRace.API" Version="$(SqlRaceApiVersion)" />
     <PackageReference Include="Microsoft.Extensions.Configuration" Version="8.*" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.*" />
     <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.*" />