Table of Contents

SQL Server Data Types in the .NET Framework

Collation and CLR Integration Data Types
Handling Large Object (LOB) Parameters in the CLR
Mapping CLR Parameter Data
Nullability and Three-Value Logic Comparisons
 SQL Server Data Types in the .NET Framework
3/24/2017 1 min to read Edit Online

The SqlTypes library is part of the base class library of the Microsoft .NET Framework. It is designed to provide
data types with the same semantics and precision as those found in the SQL Server database. This topic describes
the new semantics to .NET Framework programmers, and introduces the types implemented in the
System.Data.SqlTypes namespace that is included in the System.Data library.
This following table lists the topics in this section.
Nullability and Three-Value Logic Comparisons
Discusses how NULL values are handled with common language runtime (CLR) integration data types.
Collation and CLR Integration Data Types
Describes how collations are handled with CLR integration.
Handling Large Object (LOB) Parameters in the CLR
Describes how to pass LOB types between SQL Server and the CLR.
Mapping CLR Parameter Data
Shows data type mappings between SQL Server, CLR integration, and the .NET Framework.
 Collation and CLR Integration Data Types
3/24/2017 1 min to read Edit Online

In the .NET Framework, the CompareInfo object handles collations. The .NET Framework string application
programming interfaces (APIs) use the CompareInfo property associated with the CultureInfo object of the
current thread to perform string comparisons. The default setting of the CultureInfo object is based on the
Microsoft Windows locale setting for the computer on which Microsoft SQL Server is running. This determines the
default comparison semantics, if no explicit CultureInfo is specified, for comparisons of System.String values.
SQL Server does not explicitly change the CompareInfo property to the database or server collation. If required,
users must set the appropriate CompareInfo property in their routines.

Parameter Collation
When you create a common language runtime (CLR) routine, and a parameter of a CLR method bound to the
routine is of type SQLString, SQL Server creates an instance of the parameter with the default collation of the
database containing the calling routine. If a parameter is not a SqlType (for example, String rather than
SQLString), the collation information from the database is not associated with the parameter.

See Also
SQL Server Data Types in the .NET Framework
 Handling Large Object (LOB) Parameters in the CLR
3/24/2017 1 min to read Edit Online

Use SqlBytes and SqlChars to pass large object (LOB) binary type (varbinary(max)) and LOB character type
(nvarchar(max)) parameters, respectively. These types allow streaming the LOB values from the database to the
common language runtime (CLR) routine, instead of copying the entire value into managed space. SqlBinary and
SqlString should be used only for small binary and character string values.

See Also
SQL Server Data Types in the .NET Framework
 Mapping CLR Parameter Data
3/24/2017 2 min to read Edit Online

The following table lists Microsoft SQL Server data types, their equivalents in the common language runtime (CLR)
for SQL Server in the System.Data.SqlTypes namespace, and their native CLR equivalents in the Microsoft .NET
Framework.

SQL Server data type Type (in System.Data.SqlTypes or CLR data type (.NET Framework)
Microsoft.SqlServer.Types)

bigint SqlInt64 Int64, Nullable<Int64>

binary SqlBytes, SqlBinary Byte[]

bit SqlBoolean Boolean, Nullable<Boolean>

char None None

cursor None None

date SqlDateTime DateTime, Nullable<DateTime>

datetime SqlDateTime DateTime, Nullable<DateTime>

datetime2 None DateTime, Nullable<DateTime>

DATETIMEOFFSET None DateTimeOffset,

Nullable<DateTimeOffset>

decimal SqlDecimal Decimal, Nullable<Decimal>

float SqlDouble Double, Nullable<Double>

geography SqlGeography None

SqlGeography is defined in
Microsoft.SqlServer.Types.dll, which is
installed with SQL Server and can be
downloaded from the SQL Server 2017
feature pack.

geometry SqlGeometry None

SqlGeometry is defined in
Microsoft.SqlServer.Types.dll, which is
installed with SQL Server and can be
downloaded from the SQL Server 2017
feature pack.
hierarchyid SqlHierarchyId None

SqlHierarchyId is defined in
Microsoft.SqlServer.Types.dll, which is
installed with SQL Server and can be
downloaded from the SQL Server 2017
feature pack.

image None None

int SqlInt32 Int32, Nullable<Int32>

money SqlMoney Decimal, Nullable<Decimal>

nchar SqlChars, SqlString String, Char[]

ntext None None

numeric SqlDecimal Decimal, Nullable<Decimal>

nvarchar SqlChars, SqlString String, Char[]

SQLChars is a better match for data

transfer and access, and SQLString is a
better match for performing String
operations.

nvarchar(1), nchar(1) SqlChars, SqlString Char, String, Char[], Nullable<char>

real SqlSingle (the range of SqlSingle, Single, Nullable<Single>

however, is larger than real)

rowversion None Byte[]

smallint SqlInt16 Int16, Nullable<Int16>

smallmoney SqlMoney Decimal, Nullable<Decimal>

sql_variant None Object

table None None

text None None

time None TimeSpan, Nullable<TimeSpan>

timestamp None None

tinyint SqlByte Byte, Nullable<Byte>

uniqueidentifier SqlGuid Guid, Nullable<Guid>

 User-defined type(UDT) None The same class that is bound to the
user-defined type in the same assembly
or a dependent assembly.

varbinary SqlBytes, SqlBinary Byte[]

varbinary(1), binary(1) SqlBytes, SqlBinary byte, Byte[], Nullable<byte>

varchar None None

xml SqlXml None

Automatic Data Type Conversion with Out Parameters

A CLR method can return information to the calling code or program by marking an input parameter with the out
modifier (Microsoft Visual C#) or <Out()> ByRef (Microsoft Visual Basic) If the input parameter is a CLR data type
in the System.Data.SqlTypes namespace, and the calling program specifies its equivalent SQL Server data type as
the input parameter, a type conversion occurs automatically when the CLR method returns the data type.
For example, the following CLR stored procedure has an input parameter of SqlInt32 CLR data type that is marked
with out (C#) or <Out()> ByRef (Visual Basic):

[Microsoft.SqlServer.Server.SqlProcedure]
public static void PriceSum(out SqlInt32 value)
{ }

\<Microsoft.SqlServer.Server.SqlProcedure> _
Public Shared Sub PriceSum( \<Out()> ByRef value As SqlInt32)

End Sub

After the assembly is built and created in the database, the stored procedure is created in SQL Server with the
following Transact-SQL, which specifies a SQL Server data type of int as an OUTPUT parameter:

CREATE PROCEDURE PriceSum (@sum int OUTPUT)

AS EXTERNAL NAME TestStoredProc.StoredProcedures.PriceSum

When the CLR stored procedure is called, the SqlInt32 data type is automatically converted to an int data type, and
returned to the calling program.
Not all CLR data types can be automatically converted to their equivalent SQL Server data types through an out
parameter, however. The following table lists these exceptions.

CLR data type (SQL Server) SQL Server data type

Decimal smallmoney

SqlMoney smallmoney

Decimal money
 DateTime smalldatetime

SQLDateTime smalldatetime

Change History
UPDATED CONTENT

Added SqlGeography, SqlGeometry, and SqlHierarchyId types to the mapping table.

See Also
SQL Server Data Types in the .NET Framework
 Nullability and Three-Value Logic Comparisons
3/24/2017 1 min to read Edit Online

If you are familiar with the SQL Server data types, you will find similar semantics and precision in the
System.Data.SqlTypes namespace in the .NET Framework. There are some differences, however, and this topic
covers the most important of these differences.

NULL Values
A primary difference between native common language runtime (CLR) data types and SQL Server data types is that
the former do not allow for NULL values, while the latter provide full NULL semantics.
Comparisons are affected by NULL values. When comparing two values x and y, if either x or y is NULL, then some
logical comparisons evaluate to an UNKNOWN value rather than true or false.

SqlBoolean Data Type

The System.Data.SqlTypes namespace introduces a SqlBoolean type to represent this 3-value logic.
Comparisons between any SqlTypes return a SqlBoolean value type. The UNKNOWN value is represented by the
null value of the SqlBoolean type. The properties IsTrue, IsFalse, and IsNull are provided to check the value of a
SqlBoolean type.

Operations, Functions, and NULL Values

All arithmetic operators (+, -, *, /, %), bitwise operators (~, &, and |), and most functions return NULL if any of the
operands or arguments of SqlTypes are NULL. The IsNull property always returns a true or false value.

Precision
Decimal data types in the .NET Framework CLR have different maximum values than those of the numeric and
decimal data types in SQL Server. In addition, in the .NET Framework CLR decimal data types assume the maximum
precision. In the CLR for SQL Server, however, SqlDecimal provides the same maximum precision and scale, and
the same semantics as the decimal data type in SQL Server.

Overflow Detection
In the .NET Framework CLR, the addition of two very large numbers may not throw an exception. Instead, if no
check operator has been used, the returned result may "wrap around" as a negative integer. In
System.Data.SqlTypes, exceptions are thrown for all overflow and underflow errors, and divide-by-zero errors.

See Also
SQL Server Data Types in the .NET Framework