Zongsoft.Data.MsSql 7.17.0

Zongsoft.Data.MsSql Data Driver Plugin Library

English | 简体中文

Overview

Zongsoft.Data.MsSql is a low-level data engine driver in the Zongsoft open-source framework. It provides access to Microsoft SQL Server and is transparent to upper-layer applications; deploy this plugin library to the application plugin directory to enable it.

When to Use This Driver

Choose this package when a Zongsoft data model is stored in Microsoft SQL Server. The public application contract remains IDataAccess/IDataService<T>; this package translates expressions and mutations into the database dialect and creates connections through Microsoft.Data.SqlClient.

SQL Server quoting, identity retrieval, paging, parameters, and bulk import are emitted by this dialect. Server permissions and transaction isolation remain deployment concerns.

Installation and Plugin Deployment

dotnet add package Zongsoft.Data.MsSql

Deploy Zongsoft.Data.MsSql.plugin with the assembly. Its manifest registers the connection-settings parser and data driver under the framework workbench. A NuGet reference without the plugin manifest does not activate the driver in a plugin host.

Connection Configuration

<options>
	<option path="/Data">
		<connectionSettings default="Application">
			<connectionSetting connectionSetting.name="Application"
			                   driver="MsSql"
			                   value="Server=localhost;Database=docs;IntegratedSecurity=true" />
		</connectionSettings>
	</option>
</options>

The driver value is case-insensitive but should use the canonical MsSql spelling. The value follows the Core settings contract: it contains explicit driver parameters and extension properties. GetOptions() maps driver parameters to the native options consumed by Microsoft.Data.SqlClient; extension properties remain in the framework settings and its complete Value. For native provider capabilities, consult the provider documentation for supported keywords.

💡 Keep entity mappings, criteria, paging, transactions, and IDataAccess usage in the shared Zongsoft.Data guide. Switching drivers should not require application services to depend on provider connection classes.

The connection string uses this driver's public settings model, which does not necessarily expose every underlying SDK keyword. Examples target local test environments only. Prepare databases, accounts and permissions, and replace explicitly marked test credentials; this is not a server initialization script.

Access Through Application Contracts

The consumer module references Core; the host deploys Data and this driver. After startup, obtain the accessor matching the configured connection name:

using Zongsoft.Data;
using Zongsoft.Services;

var provider = ApplicationContext.Current.Services
	.ResolveRequired<Zongsoft.Services.IServiceProvider<IDataAccess>>();
var data = provider.GetService("Application")
	?? throw new InvalidOperationException("Data accessor not found.");
Console.WriteLine(data.Name);

See the Data plugin example for host configuration and named accessors. Prepare tables and field types for the selected database, and use the operations supported by this driver. Application services access data through the public contracts.

Runtime Behavior

This driver enables Multiple Active Result Sets (MARS) by default, allowing multiple active readers to share one session connection. Set MultipleActiveResultSets=False to disable it; additional readers then use independent connections while another reader remains active. Connection sharing follows each data source's effective connection settings.

Use the asynchronous methods on IDataAccess / IDataService<T> and consume query results with await foreach. Await transaction completion, rollback, and resource disposal. Imports accept in-memory collections and asynchronous sources, and operations propagate cancellation tokens.

Imports prepare and write batches of at most 1024 rows, enumerating the input once. By default, batches share the session transaction. Without an ambient transaction, the operation commits after all batches succeed and rolls back its transaction on failure or cancellation. With an ambient transaction, the caller controls completion. When ambient transaction enlistment is explicitly suppressed, completed batches are unaffected by the caller's rollback and may remain after later input or write failures.

🚨 Never commit production connection strings. Use deployment-time configuration or a secret provider, grant the database identity only the required permissions, and verify destructive mutations against a disposable database first.

Compatibility and Testing

Database behavior is not completely portable. Verify identifier casing, null and comparison rules, date/time precision, generated values, transaction semantics, and bulk-import constraints on the same server/provider versions used in production. Repository tests require an explicitly configured disposable database and are not ordinary offline unit tests.

Related Resources

• Zongsoft.Data user guide
• Driver implementation rules
• Data engine implementation skill
• Microsoft SQL Server provider documentation

Plugin-Based Integration

Compose this feature through the host; a package reference supplies compile-time APIs, while plugin loading also requires deployed manifests and runtime assets. See the complete plugin workflow.

The manifest adds the driver to /Workbench/Data/Drivers and the connection-settings registry. Configure the exact driver key shown above, deploy the application's mapping, then obtain IDataAccess from the host. Database creation/migration remains an explicit application operation.

Add this fragment to an existing host .deploy (retain Main and the host’s other base manifests; do not replace the whole file):

[plugins zongsoft data]
nuget:Zongsoft.Data

[plugins zongsoft data mssql]
nuget:Zongsoft.Data.MsSql

Run dotnet deploy against a test deployment as explained in the workflow, with the host's framework, platform, architecture and, where needed, site. Pin compatible versions in real deployments; application dependencies such as databases, caches or commercial runtimes are still separate prerequisites.

Additional artifacts listed by the deployment manifest include Zongsoft.Data.MsSql.plugin. Retain assemblies, dependencies and satellite resource directories as well. Restart the host after deployment, check plugin loading and service/driver registration, then verify the workflow above; copied files alone do not prove that the feature is active.