`ExcludeAssets="runtime"` ignored by Microsoft.Data.SqlClient.SNI package - native DLLs copied unconditionally

[Matteo-T]

Title

ExcludeAssets="runtime" ignored by Microsoft.Data.SqlClient.SNI package - native DLLs copied unconditionally

Description

The Microsoft.Data.SqlClient.SNI package does not respect ExcludeAssets="runtime" on the parent Microsoft.Data.SqlClient package reference. Native SNI DLLs (Microsoft.Data.SqlClient.SNI.x64.dll, x86.dll, arm64.dll and their PDBs) are copied to the output directory even when runtime assets should be excluded.

Steps to Reproduce

1. Create a .NET Framework 4.7.2 project
2. Add package reference with runtime exclusion:

<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" ExcludeAssets="runtime" PrivateAssets="all" />

3. Build the project
4. Check the output directory

Expected Behavior

With ExcludeAssets="runtime", no runtime DLLs or PDBs from Microsoft.Data.SqlClient or its dependencies should be copied to the output directory.

Actual Behavior

The following files are copied to the output directory despite the exclusion:

• Microsoft.Data.SqlClient.SNI.x64.dll
• Microsoft.Data.SqlClient.SNI.x64.pdb
• Microsoft.Data.SqlClient.SNI.x86.dll
• Microsoft.Data.SqlClient.SNI.x86.pdb
• Microsoft.Data.SqlClient.SNI.arm64.dll
• Microsoft.Data.SqlClient.SNI.arm64.pdb

Root Cause

The Microsoft.Data.SqlClient.SNI package (version 6.0.2) contains a .targets file at:

• build/net462/Microsoft.Data.SqlClient.SNI.targets
• buildTransitive/net462/Microsoft.Data.SqlClient.SNI.targets

This targets file unconditionally injects CopySNIFiles into the build process:

<PropertyGroup>
  <BuildDependsOn>
	$(BuildDependsOn);
	CopySNIFiles;
  </BuildDependsOn>
  <PrepareForRunDependsOn>
	$(PrepareForRunDependsOn);
	CopySNIFiles;
  </PrepareForRunDependsOn>
</PropertyGroup>

This bypasses NuGet's ExcludeAssets mechanism entirely.

Investigation Results

Adding diagnostic MSBuild targets confirmed that NuGet correctly excludes the assets:

• RuntimeCopyLocalItems: empty ✓
• NativeCopyLocalItems: empty ✓
• ReferenceCopyLocalPaths: empty ✓

However, the custom CopySNIFiles target runs directly through BuildDependsOn, ignoring the exclusion.

Workaround

Users must exclude build assets as well to prevent the targets file from being imported:

<PackageReference Include="Microsoft.Data.SqlClient" 
				  ExcludeAssets="runtime;build;buildTransitive" 
				  PrivateAssets="all" />

This is not ideal as it prevents all build-time functionality, not just the problematic copy behavior.

Suggested Fixes

Option 1: Add opt-out property (Quick fix)

<PropertyGroup>
  <!-- Allow users to opt out of SNI file copying -->
  <CopySNIFiles Condition="'$(CopySNIFiles)' == ''">true</CopySNIFiles>
</PropertyGroup>

<PropertyGroup>
  <BuildDependsOn Condition="'$(CopySNIFiles)' == 'true'">
	$(BuildDependsOn);
	CopySNIFiles;
  </BuildDependsOn>
  <PrepareForRunDependsOn Condition="'$(CopySNIFiles)' == 'true'">
	$(PrepareForRunDependsOn);
	CopySNIFiles;
  </PrepareForRunDependsOn>
</PropertyGroup>

Option 2: Use NuGet runtime assets (Best practice)

Remove the custom .targets file and properly package SNI DLLs as runtime assets using the runtimes/{rid}/native/ folder structure in the .nupkg. This would automatically respect ExcludeAssets="runtime".

Option 3: Check for exclusion markers

The targets file could check MSBuild properties or item metadata to detect if runtime assets should be excluded, though this is complex and fragile.

Environment

• Microsoft.Data.SqlClient version: 7.0.0
• Microsoft.Data.SqlClient.SNI version: 6.0.2 (transitive dependency for net462/net472)
• Target Framework: .NET Framework 4.7.2 (net472)
• SDK Style: Yes
• NuGet Package Management: Central Package Management

Additional Context

This issue affects scenarios where:

• Projects need compile-time references but not runtime deployment
• Projects want to control exactly which native DLLs are deployed
• Build output cleanliness is important
• Custom deployment strategies are used

[Matteo-T]

Related Issues

I searched for similar issues before filing this. While there are several issues related to SNI file deployment problems, none specifically address the ExcludeAssets="runtime" attribute being ignored:

Similar but Different Issues:

• #2998 (closed) - "Improve SNI package architecture and targets file design"

  • About general improvements to SNI targets file architecture
  • Discussed FileWrites tracking and IncrementalClean problems
  • Did not address ExcludeAssets being ignored

• #3525 (open) - "Microsoft.Data.SqlClient.SNI files ends up in root folder"

  • About SNI files being copied to wrong location when using OutDir property
  • Related to CopySNIFiles target but different symptom

• #936 (open) - "Microsoft.Data.SqlClient.SNI not deployed to _PublishedWebsites for an ASP.NET Web Application"

  • About SNI files NOT being deployed in web app scenarios
  • Opposite problem - files not copied when they should be

• #3081 (open) - "PublishSNIFiles is part of PublishItemsOutputGroupDependsOn, but doesn't contribute to PublishItemsOutputGroupOutputs"

  • About publish targets not properly contributing to output groups
  • Related to publish scenarios, not build-time ExcludeAssets

• #446 (open) - "Microsoft.Data.SqlClient.SNI not deployed along with WebForms"

  • About SNI files not being deployed in WebForms projects
  • Again, opposite problem

• #2173 (open) - "Project that contains a and references Microsoft.Data.SqlClient.SNI causes duplicate entries in manifest file"

  • About duplicate manifest entries in ClickOnce scenarios
  • Different issue entirely

Why This Issue is Unique:

This issue specifically reports that:

1. The ExcludeAssets="runtime" NuGet attribute is completely ignored by the SNI package
2. NuGet correctly excludes assets (confirmed via diagnostic targets showing empty RuntimeCopyLocalItems, NativeCopyLocalItems, etc.)
3. The SNI targets file bypasses NuGet's asset exclusion by injecting directly into BuildDependsOn
4. Users have no way to prevent SNI file copying without also excluding all build assets (ExcludeAssets="build;buildTransitive")

This is a fundamental design issue with how the SNI package interacts with NuGet's asset exclusion mechanism, not a deployment path or missing file issue.

[Matteo-T]

Here's the proposed (by my droid :)) fix:

Proposed Fix: Use NuGet Runtime Assets for .NET Framework (Option 2)

Key Insight

Microsoft.Data.SqlClient 7.0.0 already solves this problem for .NET 8+ by using the Microsoft.Data.SqlClient.SNI.runtime package, which properly respects ExcludeAssets="runtime".

The bug only affects .NET Framework projects because they still use the legacy Microsoft.Data.SqlClient.SNI package with problematic custom .targets files.

The fix is simple: Make .NET Framework use the same runtime package that .NET 8+ already uses successfully.

Overview

Good news: Microsoft.Data.SqlClient 7.0.0 already uses the proper runtime package (Microsoft.Data.SqlClient.SNI.runtime) for .NET Core/5+. The issue only affects .NET Framework projects, which still use the legacy Microsoft.Data.SqlClient.SNI package with custom .targets files.

The fix: Apply the same runtime asset pattern to .NET Framework that's already working for .NET Core/5+.

Current State (Microsoft.Data.SqlClient 7.0.0)

Dependencies in Microsoft.Data.SqlClient.nuspec:

<!-- .NET Framework 4.6.2 -->
<group targetFramework=".NETFramework4.6.2">
  <dependency id="Microsoft.Data.SqlClient.SNI" version="6.0.2" />
  <!-- ... other dependencies ... -->
</group>

<!-- .NET 8.0 and later -->
<group targetFramework="net8.0">
  <dependency id="Microsoft.Data.SqlClient.SNI.runtime" version="6.0.2" exclude="Compile" />
  <!-- ... other dependencies ... -->
</group>

The Problem:

• ✅ .NET 8+: Uses Microsoft.Data.SqlClient.SNI.runtime → respects ExcludeAssets="runtime"
• ❌ .NET Framework: Uses Microsoft.Data.SqlClient.SNI → ignores ExcludeAssets="runtime" due to custom .targets file

Current Package Structure (Problematic - .NET Framework only)

Microsoft.Data.SqlClient.SNI (version 6.0.2) - Used by .NET Framework projects:

microsoft.data.sqlclient.sni/6.0.2/
├── build/
│   └── net462/
│       └── Microsoft.Data.SqlClient.SNI.targets  ← Custom copy logic (PROBLEM)
├── buildTransitive/
│   └── net462/
│       └── Microsoft.Data.SqlClient.SNI.targets
└── runtimes/
	└── win/
		└── native/
			├── Microsoft.Data.SqlClient.SNI.x64.dll
			├── Microsoft.Data.SqlClient.SNI.x86.dll
			└── Microsoft.Data.SqlClient.SNI.arm64.dll

Microsoft.Data.SqlClient.SNI.runtime (version 6.0.2) - Used by .NET 8+ projects:

microsoft.data.sqlclient.sni.runtime/6.0.2/
└── runtimes/
	├── win-x64/native/Microsoft.Data.SqlClient.SNI.dll  ← Proper structure ✅
	├── win-x86/native/Microsoft.Data.SqlClient.SNI.dll  ← Respects ExcludeAssets ✅
	└── win-arm64/native/Microsoft.Data.SqlClient.SNI.dll
	└── (also linux and osx RIDs)

Proposed Solution

Option A (Simplest): Make .NET Framework use the existing Microsoft.Data.SqlClient.SNI.runtime package

Update Microsoft.Data.SqlClient.nuspec:

<!-- Before -->
<group targetFramework=".NETFramework4.6.2">
  <dependency id="Microsoft.Data.SqlClient.SNI" version="6.0.2" />
</group>

<!-- After -->
<group targetFramework=".NETFramework4.6.2">
  <dependency id="Microsoft.Data.SqlClient.SNI.runtime" version="6.0.2" exclude="Compile" />
</group>

Option B (If compatibility concerns exist): Update the legacy Microsoft.Data.SqlClient.SNI package to remove the .targets file and use the same RID-specific structure as the runtime package.

Proposed Package Structure

Since Microsoft.Data.SqlClient.SNI.runtime already exists with the correct structure, the fix is simply to use it for .NET Framework as well.

Why This Works for .NET Framework SDK-Style Projects

The Microsoft.Data.SqlClient.SNI.runtime package already has the correct structure that works for .NET 8+. .NET Framework SDK-style projects (like net472) can use the same package because:

1. SDK-style projects support runtime assets even when targeting .NET Framework
2. The Microsoft.NET.Sdk includes the necessary targets to handle runtimes/{rid}/native/ assets
3. RID inference works correctly - the SDK selects win-x64 or win-x86 based on the platform target

With this structure, the .NET SDK's built-in targets (from Microsoft.NET.Sdk) automatically:

1. Select the correct RID based on the target platform and architecture
2. Copy native assets to the output directory via the ResolvePackageAssets target
3. Respect ExcludeAssets="runtime" - if runtime assets are excluded, native files are NOT copied
4. Include in publish - native assets are automatically included in dotnet publish output
5. Work with self-contained deployments - correct RID-specific assets are included

How It Works Internally

The SDK's Microsoft.NET.Sdk.targets includes logic like:

<Target Name="ResolvePackageAssets">
  <!-- Resolves runtime assets from packages -->
  <ResolvePackageAssets 
	  ProjectPath="$(MSBuildProjectFullPath)"
	  TargetFramework="$(TargetFramework)"
	  RuntimeIdentifier="$(RuntimeIdentifier)"
	  <!-- ... -->
	  ExcludedAssets="@(_ExcludeAssetList)">
	<Output TaskParameter="NativeCopyLocalItems" ItemName="NativeCopyLocalItems" />
  </ResolvePackageAssets>

  <!-- NativeCopyLocalItems are automatically added to ReferenceCopyLocalPaths -->
  <ItemGroup>
	<ReferenceCopyLocalPaths Include="@(NativeCopyLocalItems)" />
  </ItemGroup>
</Target>

When ExcludeAssets="runtime" is set, the ResolvePackageAssets task does not populate NativeCopyLocalItems, so nothing gets copied. No custom logic needed!

Benefits of This Approach

1. Respects ExcludeAssets

✅ ExcludeAssets="runtime" works correctly
✅ ExcludeAssets="native" would also work
✅ No workarounds needed

2. Platform Consistency

✅ Works the same way as other native packages (e.g., System.Data.SqlClient, Microsoft.Data.Sqlite)
✅ Developers already understand this pattern
✅ Tooling (NuGet, MSBuild, IDEs) handle it correctly

3. Simplified Package

✅ No custom .targets file to maintain
✅ No complex MSBuild logic
✅ Fewer edge cases and bugs

4. Better RID Support

✅ Works correctly with RuntimeIdentifier property
✅ Self-contained deployments work automatically
✅ Cross-compilation scenarios work correctly

5. Publish Support

✅ dotnet publish includes the correct native assets automatically
✅ No need for custom PublishSNIFiles target
✅ Works with all publish profiles (folder, FTP, Azure, etc.)

Migration Path

For Package Maintainers

1. Create new package Microsoft.Data.SqlClient.SNI.runtime with the new structure
2. Keep old package for backward compatibility with a deprecation notice
3. Update Microsoft.Data.SqlClient to depend on the new runtime package
4. Test thoroughly with various project types (Framework, Core, self-contained, etc.)

For Package Consumers

No changes needed! The dependency change is transparent:

<!-- Old dependency (in Microsoft.Data.SqlClient.nuspec) -->
<dependency id="Microsoft.Data.SqlClient.SNI" version="6.0.2" />

<!-- New dependency -->
<dependency id="Microsoft.Data.SqlClient.SNI.runtime" version="6.0.3" />

Users who were using the workaround can remove it:

<!-- Before (workaround) -->
<PackageReference Include="Microsoft.Data.SqlClient" 
				  ExcludeAssets="runtime;build;buildTransitive" />

<!-- After (works as expected) -->
<PackageReference Include="Microsoft.Data.SqlClient" 
				  ExcludeAssets="runtime" />

Real-World Examples

Other packages that follow this pattern successfully:

System.Data.SQLite.Core

runtimes/
├── win-x64/native/SQLite.Interop.dll
├── win-x86/native/SQLite.Interop.dll
└── linux-x64/native/libSQLite.Interop.so

Microsoft.Data.Sqlite.Core

runtimes/
├── win-x64/native/e_sqlite3.dll
├── win-x86/native/e_sqlite3.dll
├── linux-x64/native/libe_sqlite3.so
└── osx-x64/native/libe_sqlite3.dylib

SkiaSharp

runtimes/
├── win-x64/native/libSkiaSharp.dll
├── win-x86/native/libSkiaSharp.dll
├── linux-x64/native/libSkiaSharp.so
└── osx-x64/native/libSkiaSharp.dylib

All of these packages:

• ✅ Work with ExcludeAssets="runtime"
• ✅ Work with self-contained deployments
• ✅ Work with dotnet publish
• ✅ Have no custom .targets files for copying

Implementation Checklist

• Rename DLLs to remove architecture suffix (all named Microsoft.Data.SqlClient.SNI.dll)
• Restructure build output to separate by RID (win-x64, win-x86, win-arm64)
• Update .nuspec to use runtimes/{rid}/native/ structure
• Remove build/ and buildTransitive/ folders
• Delete Microsoft.Data.SqlClient.SNI.targets file
• Update Microsoft.Data.SqlClient package dependency to reference new package
• Test with .NET Framework 4.6.2+ projects
• Test with .NET 6+ projects
• Test with ExcludeAssets="runtime"
• Test with self-contained deployments
• Test with dotnet publish
• Update documentation
• Add deprecation notice to old package

Potential Concerns & Solutions

Concern: "We need the .targets file for other functionality"

Solution: If there's truly necessary build-time functionality, keep a minimal .targets file that:

1. Does NOT copy files (let NuGet SDK handle it)
2. Only sets properties or performs validation
3. Checks if it should run based on whether assets are excluded

Concern: ".NET Framework 4.6.2 doesn't support RIDs well"

Solution: .NET Framework SDK-style projects (like the user's net472 project) DO support runtime assets correctly. The Microsoft.NET.Sdk handles it. Non-SDK style projects might need a different approach, but those are increasingly rare.

Concern: "Breaking change for users"

Solution:

1. The Microsoft.Data.SqlClient.SNI.runtime package already exists
2. Just change the dependency in Microsoft.Data.SqlClient for .NET Framework target frameworks
3. Main package (Microsoft.Data.SqlClient) switches dependency transparently
4. Users see no breaking changes unless they directly reference the SNI package
5. This brings .NET Framework in line with .NET 8+ which already uses the runtime package

Summary

This approach:

• ✅ Fixes the ExcludeAssets="runtime" bug for .NET Framework
• ✅ Uses existing Microsoft.Data.SqlClient.SNI.runtime package - no new package needed
• ✅ Achieves parity with .NET 8+ - same package, same behavior
• ✅ Eliminates complex custom MSBuild logic for .NET Framework
• ✅ Aligns with NuGet and .NET SDK best practices
• ✅ Reduces maintenance burden - one package for all platforms
• ✅ Improves reliability across scenarios
• ✅ No breaking changes for end users

This is the "right" fix that solves the root cause rather than patching symptoms. The runtime package already exists and works perfectly for .NET 8+ - just extend it to .NET Framework SDK-style projects.

[benrr101]

Hey @Matteo-T thanks for your feedback. My big question is: what scenario does this behavior become a problem?

The SqlClient binaries are OS-specific, so excluding runtime DLLs excludes the implementation assemblies. You'd end up running against the lib binaries that universally throw PlatformNotSupported exception. So I'm not sure what benefit there'd be to excluding the runtime assets for SqlClient.

Additionally, the SNI binaries are required for SqlClient to work on net462 and net8/net9 on Windows by default (unless the runtime switch to use managed SNI is turned on). We've had many issues in the past raised because the SNI binaries weren't copied into the user's project correctly, so the unconditional copying of SNI binaries aims to resolve that.

While I agree, the current behavior is a bit of a sledgehammer approach, I'd like to understand the scenarios where its harmful before making it a higher priority issue.

[cheenamalhotra]

Thanks for the issue and recommendation here @Matteo-T

We have discussed this possibility internally before about integrating the 2 SNI NuGet packages into one, however, we needed to evaluate the impact of downloading the binaries for respective architectures, as our design currently doesn't support that.

cc @David-Engel for awareness too.

We may be able to resolve multiple Native SNI library loading issues with this resolution - I'm bumping up the priority to consider this sooner.