From 2bcc383dfa7ca0be1b91c1d49450b494ea4a2541 Mon Sep 17 00:00:00 2001
From: Giorgio Bozio <giorgio.bozio@gmail.com>
Date: Thu, 8 Oct 2026 16:51:21 +0200
Subject: [PATCH] Validate the NuGet package and test the demo app against it

- Enable package validation with 1.4.0 as the baseline: packing now fails
  on API differences between target frameworks or breaking changes since
  the last release. The two existing, intentional differences are recorded
  in CompatibilitySuppressions.xml.
- DemoApp can reference the packed .nupkg instead of the project
  (UseRotativaPackage + RotativaPackageVersion), restored through
  package-test.nuget.config so the package comes only from the local feed.
- Dockerfile: USE_ROTATIVA_PACKAGE=true packs the library, builds the demo
  app against the package and checks deps.json confirms it.
- CI runs the test job for both project and package.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/tests.yml                   | 12 ++++++++++--
 README.md                                     |  4 ++++
 .../Rotativa.AspNetCore.DemoApp.csproj        | 12 +++++++++++-
 Rotativa.AspNetCore.Tests/Dockerfile          | 19 ++++++++++++++++---
 .../Dockerfile.dockerignore                   |  1 +
 .../package-test.nuget.config                 | 18 ++++++++++++++++++
 .../CompatibilitySuppressions.xml             | 16 ++++++++++++++++
 .../Rotativa.AspNetCore.csproj                |  4 ++++
 8 files changed, 80 insertions(+), 6 deletions(-)
 create mode 100644 Rotativa.AspNetCore.Tests/package-test.nuget.config
 create mode 100644 Rotativa.AspNetCore/CompatibilitySuppressions.xml

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 82b8fd1..97f5bfa 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -24,13 +24,21 @@ jobs:
         run: dotnet build Rotativa.AspNetCore/Rotativa.AspNetCore.csproj -c Release
 
   test:
-    name: Unit and integration tests (Linux)
+    name: Tests against ${{ matrix.source }} (Linux)
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # project: demo app references the library project.
+        # package: demo app references the packed .nupkg, to test the package itself.
+        source: [project, package]
     steps:
       - uses: actions/checkout@v7
 
       - name: Build test image
-        run: docker build -f Rotativa.AspNetCore.Tests/Dockerfile -t rotativa-tests .
+        run: >
+          docker build -f Rotativa.AspNetCore.Tests/Dockerfile -t rotativa-tests
+          --build-arg USE_ROTATIVA_PACKAGE=${{ matrix.source == 'package' }} .
 
       - name: Run tests
         run: docker run --rm rotativa-tests
diff --git a/README.md b/README.md
index 20bb63f..3b0c87e 100644
--- a/README.md
+++ b/README.md
@@ -164,6 +164,10 @@ docker build -f Rotativa.AspNetCore.Tests/Dockerfile -t rotativa-tests .
 docker run --rm rotativa-tests
 ```
 
+Add `--build-arg USE_ROTATIVA_PACKAGE=true` to the build to pack the library and run the demo app against the `.nupkg` instead of the project, which tests the NuGet package itself.
+
+Packing the library also runs [package validation](https://learn.microsoft.com/dotnet/fundamentals/package-validation/overview): it fails on API differences between target frameworks and on breaking changes since the last published version (`PackageValidationBaselineVersion`). Intentional differences are listed in `Rotativa.AspNetCore/CompatibilitySuppressions.xml`. After publishing a release, update the baseline version to it.
+
 
 ## rotativa.io
 
diff --git a/Rotativa.AspNetCore.DemoApp/Rotativa.AspNetCore.DemoApp.csproj b/Rotativa.AspNetCore.DemoApp/Rotativa.AspNetCore.DemoApp.csproj
index c57bf1f..3fae954 100644
--- a/Rotativa.AspNetCore.DemoApp/Rotativa.AspNetCore.DemoApp.csproj
+++ b/Rotativa.AspNetCore.DemoApp/Rotativa.AspNetCore.DemoApp.csproj
@@ -6,8 +6,18 @@
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>
 
-  <ItemGroup>
+  <ItemGroup Condition=" '$(UseRotativaPackage)' != 'true' ">
     <ProjectReference Include="..\Rotativa.AspNetCore\Rotativa.AspNetCore.csproj" />
   </ItemGroup>
 
+  <!-- Build against the packed .nupkg instead of the project, to test the package itself.
+       Restore with Rotativa.AspNetCore.Tests/package-test.nuget.config and pass RotativaPackageVersion. -->
+  <ItemGroup Condition=" '$(UseRotativaPackage)' == 'true' ">
+    <PackageReference Include="Rotativa.AspNetCore" Version="$(RotativaPackageVersion)" />
+  </ItemGroup>
+
+  <Target Name="CheckRotativaPackageVersion" BeforeTargets="CollectPackageReferences" Condition=" '$(UseRotativaPackage)' == 'true' AND '$(RotativaPackageVersion)' == '' ">
+    <Error Text="Set RotativaPackageVersion when UseRotativaPackage is true." />
+  </Target>
+
 </Project>
diff --git a/Rotativa.AspNetCore.Tests/Dockerfile b/Rotativa.AspNetCore.Tests/Dockerfile
index 6246045..323c309 100644
--- a/Rotativa.AspNetCore.Tests/Dockerfile
+++ b/Rotativa.AspNetCore.Tests/Dockerfile
@@ -1,5 +1,5 @@
 # Runs the full test suite (unit + integration) on Linux.
-# Build from the repository root:
+# Build from the repository root (add --build-arg USE_ROTATIVA_PACKAGE=true to test the packed .nupkg):
 #   docker build -f Rotativa.AspNetCore.Tests/Dockerfile -t rotativa-tests .
 #   docker run --rm rotativa-tests
 FROM debian:bookworm-slim
@@ -19,16 +19,29 @@ RUN curl -fsSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh \
     && ln -s /usr/share/dotnet/dotnet /usr/local/bin/dotnet \
     && rm /tmp/dotnet-install.sh
 
+# true: pack the library and run the demo app against the .nupkg instead of the project.
+ARG USE_ROTATIVA_PACKAGE=false
+
 ENV DOTNET_NOLOGO=1 \
     DOTNET_CLI_TELEMETRY_OPTOUT=1 \
     CI=true \
     ROTATIVA_DEMO_URL=http://localhost:5000 \
-    ROTATIVA_CHROME_BINARY=/usr/bin/chromium
+    ROTATIVA_CHROME_BINARY=/usr/bin/chromium \
+    UseRotativaPackage=${USE_ROTATIVA_PACKAGE}
 
 WORKDIR /src
 COPY . .
 
-RUN dotnet build Rotativa.AspNetCore.DemoApp \
+RUN if [ "$UseRotativaPackage" = "true" ]; then \
+        dotnet pack Rotativa.AspNetCore -c Release -o artifacts/packages -p:GeneratePackageOnBuild=false \
+        && version=$(dotnet msbuild Rotativa.AspNetCore/Rotativa.AspNetCore.csproj -getProperty:Version) \
+        && dotnet restore Rotativa.AspNetCore.DemoApp --configfile Rotativa.AspNetCore.Tests/package-test.nuget.config -p:RotativaPackageVersion=$version \
+        && dotnet build Rotativa.AspNetCore.DemoApp --no-restore -p:RotativaPackageVersion=$version \
+        && grep -A1 "\"Rotativa.AspNetCore/$version\": {" Rotativa.AspNetCore.DemoApp/bin/Debug/net10.0/Rotativa.AspNetCore.DemoApp.deps.json \
+            | grep -q '"type": "package"' ; \
+    else \
+        dotnet build Rotativa.AspNetCore.DemoApp ; \
+    fi \
     && dotnet build Rotativa.AspNetCore.Tests \
     && ln -sf /usr/local/bin/wkhtmltopdf Rotativa.AspNetCore.DemoApp/wwwroot/Rotativa/wkhtmltopdf \
     && ln -sf /usr/local/bin/wkhtmltoimage Rotativa.AspNetCore.DemoApp/wwwroot/Rotativa/wkhtmltoimage
diff --git a/Rotativa.AspNetCore.Tests/Dockerfile.dockerignore b/Rotativa.AspNetCore.Tests/Dockerfile.dockerignore
index 090b609..8cdf2c3 100644
--- a/Rotativa.AspNetCore.Tests/Dockerfile.dockerignore
+++ b/Rotativa.AspNetCore.Tests/Dockerfile.dockerignore
@@ -5,3 +5,4 @@
 .git
 **/wwwroot/Rotativa/wkhtmltopdf
 **/wwwroot/Rotativa/wkhtmltoimage
+artifacts
diff --git a/Rotativa.AspNetCore.Tests/package-test.nuget.config b/Rotativa.AspNetCore.Tests/package-test.nuget.config
new file mode 100644
index 0000000..857d267
--- /dev/null
+++ b/Rotativa.AspNetCore.Tests/package-test.nuget.config
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Used to restore the DemoApp against a locally packed Rotativa.AspNetCore (see run-tests.sh / Dockerfile).
+     Rotativa.AspNetCore comes only from artifacts/packages; everything else from nuget.org. -->
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="local" value="../artifacts/packages" />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+  </packageSources>
+  <packageSourceMapping>
+    <packageSource key="local">
+      <package pattern="Rotativa.AspNetCore" />
+    </packageSource>
+    <packageSource key="nuget.org">
+      <package pattern="*" />
+    </packageSource>
+  </packageSourceMapping>
+</configuration>
diff --git a/Rotativa.AspNetCore/CompatibilitySuppressions.xml b/Rotativa.AspNetCore/CompatibilitySuppressions.xml
new file mode 100644
index 0000000..e7da314
--- /dev/null
+++ b/Rotativa.AspNetCore/CompatibilitySuppressions.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids -->
+<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Suppression>
+    <DiagnosticId>CP0001</DiagnosticId>
+    <Target>T:Rotativa.AspNetCore.RotativaAppBuilderExtensions</Target>
+    <Left>lib/net5.0/Rotativa.AspNetCore.dll</Left>
+    <Right>lib/net6.0/Rotativa.AspNetCore.dll</Right>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Rotativa.AspNetCore.RotativaConfiguration.Setup(Microsoft.AspNetCore.Hosting.IHostingEnvironment,System.String)</Target>
+    <Left>lib/netstandard2.0/Rotativa.AspNetCore.dll</Left>
+    <Right>lib/netcoreapp3.1/Rotativa.AspNetCore.dll</Right>
+  </Suppression>
+</Suppressions>
\ No newline at end of file
diff --git a/Rotativa.AspNetCore/Rotativa.AspNetCore.csproj b/Rotativa.AspNetCore/Rotativa.AspNetCore.csproj
index cf8d832..76d6fc5 100644
--- a/Rotativa.AspNetCore/Rotativa.AspNetCore.csproj
+++ b/Rotativa.AspNetCore/Rotativa.AspNetCore.csproj
@@ -15,6 +15,10 @@
 		<Copyright>2026 Viva Software di Bozio Giorgio</Copyright>
 		<PackageLicenseExpression>MIT</PackageLicenseExpression>
 		<PackageReadmeFile>README.md</PackageReadmeFile>
+		<!-- Check the package's API across target frameworks and against the last published release.
+		     Intentional differences are listed in CompatibilitySuppressions.xml. -->
+		<EnablePackageValidation>true</EnablePackageValidation>
+		<PackageValidationBaselineVersion>1.4.0</PackageValidationBaselineVersion>
 	</PropertyGroup>
 
 	<!--<ItemGroup>