From 49d513f9380920852a44a59d72624a921ce75987 Mon Sep 17 00:00:00 2001 From: DavoudEshtehari <61173489+DavoudEshtehari@users.noreply.github.com> Date: Fri, 25 Feb 2022 18:25:49 -0800 Subject: [PATCH] Add Microsoft.SqlServer.Server documentation (#1503) --- .../DataWorks_IBinarySerialize_Sample.cs | 104 +++++++++++++ .../DataWorks_SqlFunctionAttribute_Sample.cs | 23 +++ ...SqlUserDefinedAggregateAttribute_Sample.cs | 23 +++ ...orks_SqlUserDefinedTypeAttribute_Sample.cs | 120 +++++++++++++++ .../SqlFunctionAttribute_SqlFunction.cs | 45 ++++++ .../csharp/SqlMethod.cs | 126 ++++++++++++++++ ...serDefinedAggregateAttribute_Aggregate1.cs | 59 ++++++++ .../SqlUserDefinedTypeAttribute_Type1.cs | 133 +++++++++++++++++ .../DataWorks_IBinarySerialize_Sample.vb | 103 +++++++++++++ .../DataWorks_SqlFunctionAttribute_Sample.vb | 31 ++++ ...SqlUserDefinedAggregateAttribute_Sample.vb | 21 +++ ...orks_SqlUserDefinedTypeAttribute_Sample.vb | 114 ++++++++++++++ .../SqlFunctionAttribute_SqlFunction.vb | 47 ++++++ ...serDefinedAggregateAttribute_Aggregate1.vb | 57 +++++++ .../SqlUserDefinedTypeAttribute_Type1.vb | 116 +++++++++++++++ .../InvalidUdtException.xml | 17 --- .../DataAccessKind.xml | 26 ++++ .../Microsoft.SqlServer.Server/Format.xml | 56 +++++++ .../IBinarySerialize.xml | 56 +++++++ .../InvalidUdtException.xml | 39 +++++ .../SqlFacetAttribute.xml | 124 ++++++++++++++++ .../SqlFunctionAttribute.xml | 130 ++++++++++++++++ .../SqlMethodAttribute.xml | 68 +++++++++ .../SqlUserDefinedAggregateAttribute.xml | 134 +++++++++++++++++ .../SqlUserDefinedTypeAttribute.xml | 139 ++++++++++++++++++ .../SystemDataAccessKind.xml | 26 ++++ .../IBinarySerialize.cs | 6 +- .../InvalidUdtException.cs | 6 +- .../SqlFacetAttribute.cs | 14 +- .../SqlFunctionAttribute.cs | 30 ++-- .../SqlMethodAttribute.cs | 10 +- .../SqlUserDefinedAggregateAttribute.cs | 20 +-- .../SqlUserDefinedTypeAttribute.cs | 24 +-- .../TypeForwards.cs | 5 +- 34 files changed, 1979 insertions(+), 73 deletions(-) create mode 100644 doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_IBinarySerialize_Sample.cs create mode 100644 doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlFunctionAttribute_Sample.cs create mode 100644 doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedAggregateAttribute_Sample.cs create mode 100644 doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedTypeAttribute_Sample.cs create mode 100644 doc/samples/Microsoft.SqlServer.Server/csharp/SqlFunctionAttribute_SqlFunction.cs create mode 100644 doc/samples/Microsoft.SqlServer.Server/csharp/SqlMethod.cs create mode 100644 doc/samples/Microsoft.SqlServer.Server/csharp/SqlUserDefinedAggregateAttribute_Aggregate1.cs create mode 100644 doc/samples/Microsoft.SqlServer.Server/csharp/SqlUserDefinedTypeAttribute_Type1.cs create mode 100644 doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_IBinarySerialize_Sample.vb create mode 100644 doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlFunctionAttribute_Sample.vb create mode 100644 doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedAggregateAttribute_Sample.vb create mode 100644 doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedTypeAttribute_Sample.vb create mode 100644 doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlFunctionAttribute_SqlFunction.vb create mode 100644 doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlUserDefinedAggregateAttribute_Aggregate1.vb create mode 100644 doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlUserDefinedTypeAttribute_Type1.vb create mode 100644 doc/snippets/Microsoft.SqlServer.Server/DataAccessKind.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/Format.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/IBinarySerialize.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/InvalidUdtException.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/SqlFacetAttribute.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/SqlFunctionAttribute.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/SqlMethodAttribute.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/SqlUserDefinedAggregateAttribute.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/SqlUserDefinedTypeAttribute.xml create mode 100644 doc/snippets/Microsoft.SqlServer.Server/SystemDataAccessKind.xml diff --git a/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_IBinarySerialize_Sample.cs b/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_IBinarySerialize_Sample.cs new file mode 100644 index 0000000000..3631912ba6 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_IBinarySerialize_Sample.cs @@ -0,0 +1,104 @@ +using System; +using System.IO; +using Microsoft.SqlServer.Server; + +namespace test +{ + public class Class1 : IBinarySerialize + { + [STAThread] + static void Main(string[] args) + { + string fileName = "info.dat"; + Class1 temp = new Class1(); + + FileStream fs = new FileStream(fileName, FileMode.Create); + BinaryWriter w = new BinaryWriter(fs); + + temp.Write(w); + + w.Close(); + fs.Close(); + + fs = new FileStream(fileName, FileMode.Open, FileAccess.Read); + BinaryReader r = new BinaryReader(fs); + + temp.Read(r); + + Console.WriteLine("String value: " + temp.StringValue); + Console.WriteLine("Double value: " + temp.DoubleValue); + + r.Close(); + fs.Close(); + } + + public string StringValue; + public double DoubleValue; + + // + // The binary layout is as follows: + // Bytes 0 - 19: string text, padded to the right with null characters + // Bytes 20+: Double value + + // using Microsoft.SqlServer.Server; + public void Read(System.IO.BinaryReader r) + { + + int maxStringSize = 20; + char[] chars; + int stringEnd; + string stringValue; + double doubleValue; + + // Read the characters from the binary stream. + chars = r.ReadChars(maxStringSize); + + // Find the start of the null character padding. + stringEnd = Array.IndexOf(chars, '\0'); + + if (stringEnd == 0) + { + stringValue = null; + return; + } + + // Build the string from the array of characters. + stringValue = new String(chars, 0, stringEnd); + + // Read the double value from the binary stream. + doubleValue = r.ReadDouble(); + + // Set the object's properties equal to the values. + this.StringValue = stringValue; + this.DoubleValue = doubleValue; + } + // + + // + // The binary layout is as follows: + // Bytes 0 - 19: string text, padded to the right with null characters + // Bytes 20+: Double value + + // using Microsoft.SqlServer.Server; + public void Write(System.IO.BinaryWriter w) + { + int maxStringSize = 20; + string stringValue = "The value of PI: "; + string paddedString; + double value = 3.14159; + + // Pad the string from the right with null characters. + paddedString = stringValue.PadRight(maxStringSize, '\0'); + + // Write the string value one byte at a time. + for (int i = 0; i < paddedString.Length; i++) + { + w.Write(paddedString[i]); + } + + // Write the double value. + w.Write(value); + } + // + } +} diff --git a/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlFunctionAttribute_Sample.cs b/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlFunctionAttribute_Sample.cs new file mode 100644 index 0000000000..e35b9cad21 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlFunctionAttribute_Sample.cs @@ -0,0 +1,23 @@ +using System.IO; +using System.Collections; +using Microsoft.SqlServer.Server; + +public class Class1 +{ + +// +[SqlFunctionAttribute(FillRowMethodName = "FillFileRow")] +public static IEnumerable GetFileDetails(string directoryPath) +{ + try + { + DirectoryInfo di = new DirectoryInfo(directoryPath); + return di.GetFiles(); + } + catch (DirectoryNotFoundException dnf) + { + return new string[1] { dnf.ToString() }; + } +} +// +} \ No newline at end of file diff --git a/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedAggregateAttribute_Sample.cs b/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedAggregateAttribute_Sample.cs new file mode 100644 index 0000000000..34999b5dd5 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedAggregateAttribute_Sample.cs @@ -0,0 +1,23 @@ +// +using System; +using System.IO; +using Microsoft.SqlServer.Server; + +[Serializable] +[SqlUserDefinedAggregate(Microsoft.SqlServer.Server.Format.UserDefined, + IsInvariantToNulls = true, + IsInvariantToDuplicates = false, + IsInvariantToOrder = false, + MaxByteSize = 8000) + ] +public class Concatenate : Microsoft.SqlServer.Server.IBinarySerialize +{ + public void Read(BinaryReader r) + { + } + + public void Write(BinaryWriter w) + { + } +} +// diff --git a/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedTypeAttribute_Sample.cs b/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedTypeAttribute_Sample.cs new file mode 100644 index 0000000000..90bfccfce4 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedTypeAttribute_Sample.cs @@ -0,0 +1,120 @@ +using System; +using System.Data.SqlTypes; +using Microsoft.SqlServer.Server; +using System.Text; + +// +[Serializable] +[Microsoft.SqlServer.Server.SqlUserDefinedType(Format.Native, + IsByteOrdered=true, + Name="Point",ValidationMethodName = "ValidatePoint")] +public struct Point : INullable +{ +// + private bool is_Null; + private int _x; + private int _y; + + public bool IsNull + { + get + { + return (is_Null); + } + } + + public static Point Null + { + get + { + Point pt = new Point(); + pt.is_Null = true; + return pt; + } + } + + // Use StringBuilder to provide string representation of UDT. + public override string ToString() + { + // Since InvokeIfReceiverIsNull defaults to 'true' + // this test is unnecessary if Point is only being called + // from SQL. + if (this.IsNull) + { + return "NULL"; + } + else + { + StringBuilder builder = new StringBuilder(); + builder.Append(_x); + builder.Append(","); + builder.Append(_y); + return builder.ToString(); + } + } + + [SqlMethod(OnNullCall = false)] + public static Point Parse(SqlString s) + { + // With OnNullCall=false, this check is unnecessary if + // Point only called from SQL. + if (s.IsNull) + return Null; + + // Parse input string to separate out points. + Point pt = new Point(); + string[] xy = s.Value.Split(",".ToCharArray()); + pt.X = int.Parse(xy[0]); + pt.Y = int.Parse(xy[1]); + + // Call ValidatePoint to enforce validation + // for string conversions. + if (!pt.ValidatePoint()) + throw new ArgumentException("Invalid XY coordinate values."); + return pt; + } + + // X and Y coordinates exposed as properties. + public int X + { + get + { + return this._x; + } + // Call ValidatePoint to ensure valid range of Point values. + set + { + int temp = _x; + _x = value; + if (!ValidatePoint()) + { + _x = temp; + throw new ArgumentException("Invalid X coordinate value."); + } + } + } + + public int Y + { + get + { + return this._y; + } + set + { + int temp = _y; + _y = value; + if (!ValidatePoint()) + { + _y = temp; + throw new ArgumentException("Invalid Y coordinate value."); + } + } + } + + // Validation method to enforce valid X and Y values. + private bool ValidatePoint() + { + return true; + } +} diff --git a/doc/samples/Microsoft.SqlServer.Server/csharp/SqlFunctionAttribute_SqlFunction.cs b/doc/samples/Microsoft.SqlServer.Server/csharp/SqlFunctionAttribute_SqlFunction.cs new file mode 100644 index 0000000000..7317b1917b --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/csharp/SqlFunctionAttribute_SqlFunction.cs @@ -0,0 +1,45 @@ +using System.Collections; +//----------------------------------------------------------------------------- +// +using System.Data.SqlTypes; +using Microsoft.SqlServer.Server; + +public partial class UserDefinedFunctions +{ + public const double SALES_TAX = .086; + + [SqlFunction()] + public static SqlDouble addTax(SqlDouble originalAmount) + { + SqlDouble taxAmount = originalAmount * SALES_TAX; + + return originalAmount + taxAmount; + } +} +// + +//----------------------------------------------------------------------------- +// +public partial class UserDefinedFunctions +{ + [SqlFunction(Name="sp_scalarFunc")] + public static SqlString SampleScalarFunction(SqlString s) + { + //... + return ""; + } +} +// + +//----------------------------------------------------------------------------- +// +public partial class UserDefinedFunctions +{ + [SqlFunction(Name="sp_tableFunc", TableDefinition="letter nchar(1)")] + public static IEnumerable SampleTableFunction(SqlString s) + { + //... + return new ArrayList(new char[3] {'a', 'b', 'c'}); + } +} +// diff --git a/doc/samples/Microsoft.SqlServer.Server/csharp/SqlMethod.cs b/doc/samples/Microsoft.SqlServer.Server/csharp/SqlMethod.cs new file mode 100644 index 0000000000..9e41150c99 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/csharp/SqlMethod.cs @@ -0,0 +1,126 @@ +using System; +// +using Microsoft.SqlServer.Server; +using System.Data.SqlTypes; +using System.Text; + +[Serializable] +[SqlUserDefinedType(Format.Native, + IsByteOrdered = true, + Name = "Point", ValidationMethodName = "ValidatePoint")] +public struct Point : INullable +{ + + private bool is_Null; + private int _x; + private int _y; + + // Distance from Point to the specified x and y values method. + [SqlMethod(OnNullCall = false, IsMutator = false, InvokeIfReceiverIsNull = false)] + public Double DistanceFromXY(int iX, int iY) + { + return Math.Sqrt(Math.Pow(iX - _x, 2.0) + Math.Pow(iY - _y, 2.0)); + } + // + + public bool IsNull + { + get + { + return (is_Null); + } + } + + public static Point Null + { + get + { + Point pt = new Point(); + pt.is_Null = true; + return pt; + } + } + + // Use StringBuilder to provide string representation of UDT. + public override string ToString() + { + // Since InvokeIfReceiverIsNull defaults to 'true' + // this test is unnecessary if Point is only being called + // from SQL. + if (this.IsNull) + return "NULL"; + else + { + StringBuilder builder = new StringBuilder(); + builder.Append(_x); + builder.Append(","); + builder.Append(_y); + return builder.ToString(); + } + } + + [SqlMethod(OnNullCall = false)] + public static Point Parse(SqlString s) + { + // With OnNullCall=false, this check is unnecessary if + // Point only called from SQL. + if (s.IsNull) + return Null; + + // Parse input string to separate out points. + Point pt = new Point(); + string[] xy = s.Value.Split(",".ToCharArray()); + pt.X = int.Parse(xy[0]); + pt.Y = int.Parse(xy[1]); + + // Call ValidatePoint to enforce validation + // for string conversions. + if (!pt.ValidatePoint()) + throw new ArgumentException("Invalid XY coordinate values."); + return pt; + } + + // X and Y coordinates exposed as properties. + public int X + { + get + { + return this._x; + } + // Call ValidatePoint to ensure valid range of Point values. + set + { + int temp = _x; + _x = value; + if (!ValidatePoint()) + { + _x = temp; + throw new ArgumentException("Invalid X coordinate value."); + } + } + } + + public int Y + { + get + { + return this._y; + } + set + { + int temp = _y; + _y = value; + if (!ValidatePoint()) + { + _y = temp; + throw new ArgumentException("Invalid Y coordinate value."); + } + } + } + + // Validation method to enforce valid X and Y values. + private bool ValidatePoint() + { + return true; + } +} diff --git a/doc/samples/Microsoft.SqlServer.Server/csharp/SqlUserDefinedAggregateAttribute_Aggregate1.cs b/doc/samples/Microsoft.SqlServer.Server/csharp/SqlUserDefinedAggregateAttribute_Aggregate1.cs new file mode 100644 index 0000000000..edf119d940 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/csharp/SqlUserDefinedAggregateAttribute_Aggregate1.cs @@ -0,0 +1,59 @@ +//----------------------------------------------------------------------------- +// +using System; +using System.Data.SqlTypes; +using Microsoft.SqlServer.Server; + +[Serializable] +[SqlUserDefinedAggregate(Format.Native)] +public struct CountVowels +{ + // count only the vowels in the passed-in strings + private SqlInt32 countOfVowels; + + public void Init() + { + countOfVowels = 0; + } + + public void Accumulate(SqlString value) + { + // list of vowels to look for + string vowels = "aeiou"; + + // for each character in the given parameter + for (int i=0; i < value.ToString().Length; i++) + { + // for each character in the vowels string + for (int j=0; j < vowels.Length; j++) + { + // convert parameter character to lowercase and compare to vowel + if (value.Value.Substring(i,1).ToLower() == vowels.Substring(j,1)) + { + // it is a vowel, increment the count + countOfVowels+=1; + } + } + } + } + + public void Merge(CountVowels value) + { + Accumulate(value.Terminate()); + } + + public SqlString Terminate() + { + return countOfVowels.ToString(); + } +} +// + +//----------------------------------------------------------------------------- +// +[SqlUserDefinedAggregate(Format.Native)] +public class SampleAggregate +{ + //... +} +// diff --git a/doc/samples/Microsoft.SqlServer.Server/csharp/SqlUserDefinedTypeAttribute_Type1.cs b/doc/samples/Microsoft.SqlServer.Server/csharp/SqlUserDefinedTypeAttribute_Type1.cs new file mode 100644 index 0000000000..70f8d0ae7b --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/csharp/SqlUserDefinedTypeAttribute_Type1.cs @@ -0,0 +1,133 @@ +//----------------------------------------------------------------------------- +// +using System; +using System.Data.SqlTypes; +using Microsoft.SqlServer.Server; + +[Serializable()] +[SqlUserDefinedType(Format.Native)] +public struct Point : INullable +{ + private int m_x; + private int m_y; + private bool is_Null; + + public int X + { + get + { + return (this.m_x); + } + set + { + m_x = value; + } + } + + public int Y + { + get + { + return (this.m_y); + } + set + { + m_y = value; + } + } + + public bool IsNull + { + get + { + return is_Null; + } + } + + public static Point Null + { + get + { + Point pt = new Point(); + pt.is_Null = true; + return (pt); + } + } + + public override string ToString() + { + if (this.IsNull) + { + return "NULL"; + } + else + { + return this.m_x + ":" + this.m_y; + } + } + + public static Point Parse(SqlString s) + { + if (s.IsNull) + { + return Null; + } + + // Parse input string here to separate out coordinates + string str = Convert.ToString(s); + string[] xy = str.Split(':'); + + Point pt = new Point(); + pt.X = Convert.Toint(xy[0]); + pt.Y = Convert.Toint(xy[1]); + return (pt); + } + + public SqlString Quadrant() + { + if (m_x == 0 && m_y == 0) + { + return "centered"; + } + + SqlString stringReturn = ""; + + if (m_x == 0) + { + stringReturn = "center"; + } + else if (m_x > 0) + { + stringReturn = "right"; + } + else if (m_x < 0) + { + stringReturn = "left"; + } + + if (m_y == 0) + { + stringReturn = stringReturn + " center"; + } + else if (m_y > 0) + { + stringReturn = stringReturn + " top"; + } + else if (m_y < 0) + { + stringReturn = stringReturn + " bottom"; + } + + return stringReturn; + } +} +// + +//----------------------------------------------------------------------------- +// +[SqlUserDefinedType(Format.Native, MaxByteSize=8000)] +public class SampleType +{ + //... +} +// diff --git a/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_IBinarySerialize_Sample.vb b/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_IBinarySerialize_Sample.vb new file mode 100644 index 0000000000..8f96b056a4 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_IBinarySerialize_Sample.vb @@ -0,0 +1,103 @@ +Option Explicit On +Option Strict On + +Imports System +Imports System.IO +Imports Microsoft.SqlServer.Server +Imports System.Text + +Public Class Class1:Implements Microsoft.SqlServer.Server.IBinarySerialize + +Dim StringValue As String +Dim DoubleValue As Double + +Shared Sub Main() + + Dim fileName As String = "info.dat" + Dim temp As New Class1() + + Dim fs As New FileStream(fileName, FileMode.Create) + Dim w As New BinaryWriter(fs) + + temp.Write(w) + + w.Close() + fs.Close() + + fs = New FileStream(fileName, FileMode.Open, FileAccess.Read) + Dim r As New BinaryReader(fs) + + temp.Read(r) + + Console.WriteLine("String Value: " & temp.StringValue) + Console.WriteLine("Double value: " & temp.DoubleValue) + +End Sub + +' +' The binary layout is as follows: +' Bytes 0 - 19: string text, padded to the right with null +' characters +' Bytes 20+: double value +Public Sub Read(ByVal r As System.IO.BinaryReader) _ + Implements Microsoft.SqlServer.Server.IBinarySerialize.Read + + Dim maxStringSize As Integer = 20 + Dim chars As Char() + Dim stringEnd As Integer + Dim stringValue As String + Dim value As double + + ' Read the characters from the binary stream. + chars = r.ReadChars(maxStringSize) + + ' Find the start of the null character padding. + stringEnd = Array.IndexOf(chars, ControlChars.NullChar) + + If StringEnd = 0 Then + stringValue = Nothing + Exit Sub + End If + + ' Build the string from the array of characters. + stringValue = new String(chars, 0, stringEnd) + + ' Read the double value from the binary stream. + value = r.ReadDouble() + + ' Set the object's properties equal to the values. + Me.StringValue = stringValue + Me.DoubleValue = value + +End Sub +' + +' +' The binary layout is as follows: +' Bytes 0 - 19: string text, padded to the right with null characters +' Bytes 20+: Double value +Public Sub Write(ByVal w As System.IO.BinaryWriter) _ + Implements Microsoft.SqlServer.Server.IBinarySerialize.Write + + Dim maxStringSize As Integer = 20 + Dim stringValue As String = "The value of PI: " + Dim paddedString As String + Dim value As Double = 3.14159 + + ' Pad the string from the right with null characters. + paddedString = stringValue.PadRight(maxStringSize, ControlChars.NullChar) + + + ' Write the string value one byte at a time. + Dim i As Integer + For i = 0 To paddedString.Length - 1 + w.Write(paddedString(i)) + Next + + ' Write the double value. + w.Write(value) + +End Sub +' + +End Class diff --git a/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlFunctionAttribute_Sample.vb b/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlFunctionAttribute_Sample.vb new file mode 100644 index 0000000000..41c7bcffcc --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlFunctionAttribute_Sample.vb @@ -0,0 +1,31 @@ +Option Explicit On +Option Strict On + +Imports System.IO +Imports System.Collections +Imports Microsoft.SqlServer.Server + +Public Class Class1 + +' + _ +Public Shared Function GetFileDetails(ByVal directoryPath As String) As IEnumerable + + Try + + Dim di As DirectoryInfo = new DirectoryInfo(directoryPath) + return di.GetFiles() + + Catch dnf As DirectoryNotFoundException + + Dim message As String() = {dnf.ToString() } + return message + + End Try +End Function +' + + + + +End Class \ No newline at end of file diff --git a/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedAggregateAttribute_Sample.vb b/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedAggregateAttribute_Sample.vb new file mode 100644 index 0000000000..2bb1e5af98 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedAggregateAttribute_Sample.vb @@ -0,0 +1,21 @@ +' +Imports System.IO +Imports Microsoft.SqlServer.Server + + _ +Public Class Concatenate + Implements Microsoft.SqlServer.Server.IBinarySerialize + +Public Sub Read(ByVal r As BinaryReader) Implements Microsoft.SqlServer.Server.IBinarySerialize.Read + + End Sub + + Public Sub Write(ByVal w As BinaryWriter) Implements Microsoft.SqlServer.Server.IBinarySerialize.Write + + End Sub +End Class +' diff --git a/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedTypeAttribute_Sample.vb b/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedTypeAttribute_Sample.vb new file mode 100644 index 0000000000..e5b2368aa9 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedTypeAttribute_Sample.vb @@ -0,0 +1,114 @@ +Option Explicit On +Option Strict On + +Imports System.Data.SqlTypes +Imports Microsoft.SqlServer.Server +Imports System.Text + +' + _ + Public Structure Point + Implements INullable +' + Private is_Null As Boolean + Private _x As Integer + Private _y As Integer + + Public ReadOnly Property IsNull() As Boolean _ + Implements INullable.IsNull + Get + Return (is_Null) + End Get + End Property + + Public Shared ReadOnly Property Null() As Point + Get + Dim pt As New Point + pt.is_Null = True + Return (pt) + End Get + End Property + + ' Use StringBuilder to provide string representation of UDT. + Public Overrides Function ToString() As String + ' Since InvokeIfReceiverIsNull defaults to 'true' + ' this test is unneccesary if Point is only being called + ' from SQL. + If Me.IsNull Then + Return "NULL" + Else + Dim builder As StringBuilder = New StringBuilder + builder.Append(_x) + builder.Append(",") + builder.Append(_y) + Return builder.ToString + End If + End Function + + _ + Public Shared Function Parse(ByVal s As SqlString) As Point + ' With OnNullCall=False, this check is unnecessary if + ' Point only being called from SQL. + If s.IsNull Then + Return Null + End If + + ' Parse input string here to separate out points. + Dim pt As New Point() + Dim xy() As String = s.Value.Split(",".ToCharArray()) + pt.X = Integer.Parse(xy(0)) + pt.Y = Integer.Parse(xy(1)) + + ' Call ValidatePoint to enforce validation + ' for string conversions. + If Not pt.ValidatePoint() Then + Throw New ArgumentException("Invalid XY coordinate values.") + End If + Return pt + End Function + + ' X and Y coordinates are exposed as properties. + Public Property X() As Integer + Get + Return (Me._x) + End Get + + Set(ByVal Value As Integer) + Dim temp As Integer = _x + _x = Value + If Not ValidatePoint() Then + _x = temp + Throw New ArgumentException("Invalid X coordinate value.") + End If + End Set + End Property + + Public Property Y() As Integer + Get + Return (Me._y) + End Get + + Set(ByVal Value As Integer) + Dim temp As Integer = _y + _y = Value + If Not ValidatePoint() Then + _y = temp + Throw New ArgumentException("Invalid Y coordinate value.") + End If + End Set + End Property + + ' Validation method to enforce valid X and Y values. + Private Function ValidatePoint() As Boolean + ' Allow only zero or positive integers for X and Y coordinates. + If (_x >= 0) And (_y >= 0) Then + Return True + Else + Return False + End If + End Function + +End Structure diff --git a/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlFunctionAttribute_SqlFunction.vb b/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlFunctionAttribute_SqlFunction.vb new file mode 100644 index 0000000000..b308062cd4 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlFunctionAttribute_SqlFunction.vb @@ -0,0 +1,47 @@ +Imports System.Collections +'------------------------------------------------------------------------------ +' +Imports System.Data.SqlTypes +Imports Microsoft.SqlServer.Server + +Partial Public Class UserDefinedFunctions + + Public Const SALES_TAX As Double = 0.086 + + + Public Shared Function addTax(ByVal originalAmount As SqlDouble) As SqlDouble + + Dim taxAmount As SqlDouble = originalAmount * SALES_TAX + + Return originalAmount + taxAmount + End Function +End Class +' + + +'------------------------------------------------------------------------------ +' +Partial Public Class UserDefinedFunctions + + + Public Shared Function SampleScalarFunction(ByVal s As SqlString) As SqlString + + '... + Return "" + End Function +End Class +' + + +'------------------------------------------------------------------------------ +' +Partial Public Class UserDefinedFunctions + + + Public Shared Function SampleTableFunction(ByVal s As SqlString) As IEnumerable + + '... + Return New Char(2) {"a"c, "b"c, "c"c} + End Function +End Class +' diff --git a/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlUserDefinedAggregateAttribute_Aggregate1.vb b/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlUserDefinedAggregateAttribute_Aggregate1.vb new file mode 100644 index 0000000000..b2e7727c51 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlUserDefinedAggregateAttribute_Aggregate1.vb @@ -0,0 +1,57 @@ +'------------------------------------------------------------------------------ +' +Imports System +Imports System.Data.SqlTypes +Imports Microsoft.SqlServer.Server + + + +Public Structure CountVowels + + ' count only the vowels in the passed-in strings + Private countOfVowels As SqlInt32 + + + Public Sub Init() + countOfVowels = 0 + End Sub + + + Public Sub Accumulate(ByVal value As SqlString) + Dim stringChar As String + Dim indexChar As Integer + + ' for each character in the given parameter + For indexChar = 0 To Len(value.ToString()) - 1 + + stringChar = value.ToString().Substring(indexChar, 1) + + If stringChar.ToLower() Like "[aeiou]" Then + + ' it is a vowel, increment the count + countOfVowels = countOfVowels + 1 + End If + Next + End Sub + + + Public Sub Merge(ByVal value As CountVowels) + + Accumulate(value.Terminate()) + End Sub + + + Public Function Terminate() As SqlString + + Return countOfVowels.ToString() + End Function +End Structure +' + +'------------------------------------------------------------------------------ +' + +Public Class SampleAggregate + '... +End Class +' diff --git a/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlUserDefinedTypeAttribute_Type1.vb b/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlUserDefinedTypeAttribute_Type1.vb new file mode 100644 index 0000000000..effdf6bda4 --- /dev/null +++ b/doc/samples/Microsoft.SqlServer.Server/visualbasic/SqlUserDefinedTypeAttribute_Type1.vb @@ -0,0 +1,116 @@ +'------------------------------------------------------------------------------ +' +Imports System.Data.SqlTypes +Imports Microsoft.SqlServer.Server + + + +Public Structure Point + Implements INullable + + Private m_x As Integer + Private m_y As Integer + Private is_Null As Boolean + + Public Property X() As Integer + Get + Return (Me.m_x) + End Get + Set(ByVal Value As Integer) + m_x = Value + End Set + End Property + + Public Property Y() As Integer + Get + Return (Me.m_y) + End Get + Set(ByVal Value As Integer) + m_y = Value + End Set + End Property + + Public ReadOnly Property IsNull() As Boolean Implements INullable.IsNull + Get + Return is_Null + End Get + End Property + + Public Shared ReadOnly Property Null() As Point + Get + Dim pt As Point = New Point + pt.is_Null = True + Return pt + End Get + End Property + + Public Overrides Function ToString() As String + If Me.IsNull() Then + Return Nothing + Else + Return Me.m_x & ":" & Me.m_y + End If + End Function + + Public Shared Function Parse(ByVal s As SqlString) As Point + If s = SqlString.Null Then + Return Null + End If + + If s.ToString() = SqlString.Null.ToString() Then + Return Null + End If + + If s.IsNull Then + Return Null + End If + + 'Parse input string here to separate out coordinates + Dim str As String = Convert.ToString(s) + Dim xy() As String = str.Split(":"c) + + Dim pt As New Point() + pt.X = CType(xy(0), Integer) + pt.Y = CType(xy(1), Integer) + Return (pt) + End Function + + Public Function Quadrant() As SqlString + + If m_x = 0 And m_y = 0 Then + Return "centered" + End If + + Dim stringResult As String = "" + + Select Case m_x + Case 0 + stringResult = "center" + Case Is > 0 + stringResult = "right" + Case Is < 0 + stringResult = "left" + End Select + + Select Case m_y + Case 0 + stringResult = stringResult & " center" + Case Is > 0 + stringResult = stringResult & " top" + Case Is < 0 + stringResult = stringResult & " bottom" + End Select + + Return stringResult + End Function +End Structure +' + +'------------------------------------------------------------------------------ +' + +Public Class SampleType + + '... +End Class +' diff --git a/doc/snippets/Microsoft.Data.SqlClient.Server/InvalidUdtException.xml b/doc/snippets/Microsoft.Data.SqlClient.Server/InvalidUdtException.xml index 8c70c3ea78..70bfd160f4 100644 --- a/doc/snippets/Microsoft.Data.SqlClient.Server/InvalidUdtException.xml +++ b/doc/snippets/Microsoft.Data.SqlClient.Server/InvalidUdtException.xml @@ -18,22 +18,5 @@ ]]> - - The object. - The object that represents a string in string resources. The default value is `SqlUdtReason_NoUdtAttribute` which looks up a localized string similar to "no UDT attribute". - Create a new object. - A new object. - - [!IMPORTANT] -> This function exposes for backward compatibility, and should be used with default value for `resourceReason` parameter. - - ]]> - - diff --git a/doc/snippets/Microsoft.SqlServer.Server/DataAccessKind.xml b/doc/snippets/Microsoft.SqlServer.Server/DataAccessKind.xml new file mode 100644 index 0000000000..1590300ea4 --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/DataAccessKind.xml @@ -0,0 +1,26 @@ + + + + + Describes the type of access to user data for a user-defined method or function. + + and to indicate whether the method or function uses ADO.NET to connect back to the database using the "context connection." + +Note that methods and functions are not allowed to make changes to the database, so the options for this enumeration are `None` (meaning no data-access performed by the method or function) and `Read` (meaning that the method or function perform read-only data-access operations, such as executing SELECT statements). + + ]]> + + + + The method or function does not access user data. + + + The method or function reads user data. + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/Format.xml b/doc/snippets/Microsoft.SqlServer.Server/Format.xml new file mode 100644 index 0000000000..31b5776207 --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/Format.xml @@ -0,0 +1,56 @@ + + + + + Used by and to indicate the serialization format of a user-defined type (UDT) or aggregate. + + and to indicate the serialization format of a user-defined type (UDT) or aggregate. Use of the `Native` and `UserDefined` enumeration members has special requirements. + +- `Format.Native` + The requirements for the `Format.Native` format are: + + - The with a property value of must be applied to the aggregate or UDT if it is defined in a class and not a structure. This controls the physical layout of the data fields and is used to force the members to be laid out sequentially in the order they appear. SQL Server uses this attribute to determine the field order for UDTs with multiple fields. + + - The type must contain at least one member (serialized values cannot be zero bytes in size). + + - All the fields of the aggregate must be *blittable*; that is, they must have a common representation in both managed and unmanaged memory and not require special handling by the interop marshaler. + + - All the fields of the UDT should be of one of the following types that can be serialized: `bool`, `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `float`, `double`, , , , , , , , , or other value types defined by the user that contain fields of one of these types. + - The aggregate must not specify a value for `MaxByteSize`. + + - The aggregate must not have any [NonSerialized] fields. + + - Fields must not be marked as an explicit layout (with a of ). +- `Format.UserDefined` + The requirements for the `Format.UserDefined` format are: + - The aggregate must specify a value for `MaxByteSize`. + + - Specify the attribute property. The default value is `false`. + + - If you omit any field in the or methods, the state of that field is not serialized. + +## Examples + +The following example shows the `UserDefinedType` attribute of the Point UDT. The UDT is byte-ordered, is named "Point", has a validation method named "ValidatePoint", and uses the native serialization format. + +[!code-csharp[SqlUserDefinedTypeAttribute Example#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedTypeAttribute_Sample.cs#1)] +[!code-vb[SqlUserDefinedTypeAttribute Example#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedTypeAttribute_Sample.vb#1)] + + ]]> + + + + This serialization format uses a very simple algorithm that enables SQL Server to store an efficient representation of the UDT on disk. Types marked for serialization can only have value types (structs in Microsoft Visual C# and structures in Microsoft Visual Basic .NET) as members. Members of reference types (such as classes in Visual C# and Visual Basic), either user-defined or those existing in .NET class libraries (such as ), are not supported. + + + The serialization format is unknown. + + + This serialization format gives the developer full control over the binary format through the and methods. + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/IBinarySerialize.xml b/doc/snippets/Microsoft.SqlServer.Server/IBinarySerialize.xml new file mode 100644 index 0000000000..79128e5655 --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/IBinarySerialize.xml @@ -0,0 +1,56 @@ + + + + + Provides custom implementation for user-defined type (UDT) and user-defined aggregate serialization and deserialization. + + .`Native` or .`UserDefined`. + +.`Native` allows SQL Server to handle serialization and deserialization automatically, but the format has restrictions on the kind of types it can handle. .`UserDefined` allows user-defined types and aggregates to handle their own serialization. User-defined types and aggregates must be marked with .`UserDefined` in the `SqlUserDefinedType` or `SqlUserDefinedAggregate` attribute, and must implement the interface. + +Note that even with custom serialization, the total size of each instance must be under the maximum allowed limit, currently 8000 bytes. + + ]]> + + + + The stream from which the object is deserialized. + Generates a user-defined type (UDT) or user-defined aggregate from its binary form. + + method must reconstitute your object using the information written by the method. + +## Examples +The following example shows the implementation of the method of a UDT, which uses a to de-serialize a previously persisted UDT. This example assumes that the UDT has two data properties: `StringValue` and `DoubleValue`. + +[!code-csharp[IBinarySerialize Samples#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_IBinarySerialize_Sample.cs#1)] +[!code-vb[IBinarySerialize Samples#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_IBinarySerialize_Sample.vb#1)] + + ]]> + + + + The stream to which the UDT or user-defined aggregate is serialized. + Converts a user-defined type (UDT) or user-defined aggregate into its binary format so that it may be persisted. + + method to reconstitute your UDT or user-defined aggregate. + +## Examples +The following example shows the implementation of the method of a UDT, which uses a to serialize the UDT in the user-defined binary format. The purpose of the null character padding is to ensure that the string value is completely separated from the double value, so that one UDT is compared to another in Transact-SQL code, string bytes are compared to string bytes and double bytes are compared to double bytes. + +[!code-csharp[IBinarySerialize Samples#2](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_IBinarySerialize_Sample.cs#2)] +[!code-vb[IBinarySerialize Samples#2](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_IBinarySerialize_Sample.vb#2)] + + ]]> + + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/InvalidUdtException.xml b/doc/snippets/Microsoft.SqlServer.Server/InvalidUdtException.xml new file mode 100644 index 0000000000..9ec4002c76 --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/InvalidUdtException.xml @@ -0,0 +1,39 @@ + + + + + Thrown when SQL Server or the ADO.NET provider detects an invalid user-defined type (UDT). + To be added. + + + The object. + The object. + Streams all the properties into the class for the given . + + class to make the class serializable. + + ]]> + + + + The object. + The object that represents a string in string resources. The default value is `SqlUdtReason_NoUdtAttribute` which looks up a localized string similar to "no UDT attribute". + Creates a new object. + A new object. + + [!IMPORTANT] +> This function is exposed for backward compatibility and should be used with the default value for the `resourceReason` parameter. + + ]]> + + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/SqlFacetAttribute.xml b/doc/snippets/Microsoft.SqlServer.Server/SqlFacetAttribute.xml new file mode 100644 index 0000000000..cae95f8032 --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/SqlFacetAttribute.xml @@ -0,0 +1,124 @@ + + + + + Annotates the returned result of a user-defined type (UDT) with additional information that can be used in Transact-SQL. + + may only be specified on non-void return values. + + is used only to derive information about the return type, and is not intended to be a constraint specification on what can be stored in the type. Thus, if a field has a indicating its size to be 2 characters, then the SQL Server type of the field access expression is of size 2, but assignments into the field are not restricted by this facet. + +The table below captures the matrix of valid values for the various properties for specific field types. In this table, "Y" indicates that the property is valid, and "N" indicates that the property is not valid. + +The specified must be compatible with the field type. If the property is not valid, type registration will report an error if the user specifies a non-default value for the property. The maximum values for and properties are 38. For the property, the value should be in the range of 1-8000 for binary and non-Unicode data, 1-4000 for Unicode data, or -1. All other values are not valid. + +|Type|IsFixedLength|MaxSize|Precision|Scale|IsNullable| +|----------|-------------------|-------------|---------------|-----------|----------------| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|N|N|Y| +||N|N|Y|Y|Y| +||Y|Y|N|N|Y| +||Y|Y|N|N|Y| +||N|N|N|N|Y| +||Y|Y|N|N|Y| +||Y|Y|N|N|Y| +|Embedded UDTs|N|N|N|N|Y| +||Y|Y|N|N|Y| +|Byte[]|Y|Y|N|N|Y| +|Char[]|Y|Y|N|N|Y| +||N|N|N|Y1|N| +||N|N|Y|Y|Y| + +(1) Specifying the scale on a DateTime type will cause the value to be returned to Transact-SQL as a DateTime2 type with the specified scale. + + ]]> + + + + An optional attribute on a user-defined type (UDT) return type, used to annotate the returned result with additional information that can be used in Transact-SQL. + To be added. + + + Indicates whether the return type of the user-defined type is of a fixed length. + + if the return type is of a fixed length; otherwise . + + property is set to 1. + +The default value is `false`. + +]]> + + + + Indicates whether the return type of the user-defined type can be . + + if the return type of the user-defined type can be ; otherwise . + + + + + + The maximum size, in logical units, of the underlying field type of the user-defined type. + An representing the maximum size, in logical units, of the underlying field type. + + + + + + The precision of the return type of the user-defined type. + An representing the precision of the return type. + + property is valid only for numeric types. The property must also be specified when setting the property. + +The maximum value of the property is 38; the default value is 38. + + ]]> + + + + The scale of the return type of the user-defined type. + An representing the scale of the return type. + + property is valid only for decimal types. The property must also be specified when setting the property. + +The maximum value of the property is 38; the default value is 0. + + ]]> + + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/SqlFunctionAttribute.xml b/doc/snippets/Microsoft.SqlServer.Server/SqlFunctionAttribute.xml new file mode 100644 index 0000000000..ddf4c76e4b --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/SqlFunctionAttribute.xml @@ -0,0 +1,130 @@ + + + + + Used to mark a method definition of a user-defined aggregate as a function in SQL Server. The properties on the attribute reflect the physical characteristics used when the type is registered with SQL Server. + + + + + + An optional attribute on a user-defined aggregate, used to indicate that the method should be registered in SQL Server as a function. Also used to set the , , , , , , and properties of the function attribute. + To be added. + + + Indicates whether the function involves access to user data stored in the local instance of SQL Server. + + .: Does not access data. .: Only reads user data. + + . is also required when connecting to remote servers if transactions integration is required (the default). + +If a Transact-SQL query is executed from inside a table-valued function (TVF), the property should be set. + +]]> + + + + The name of a method in the same class which is used to fill a row of data in the table returned by the table-valued function. + A value representing the name of a method in the same class which is used to fill a row of data in the table returned by the table-valued function. + + + Indicates whether the user-defined function is deterministic. + + if the function is deterministic; otherwise . + + property is also useful for indexing the result of the function in the form of indexed computed columns and indexed views. If this property is not specified, the function is assumed to be non-deterministic. + +Functions that access local data can be deterministic. The data access characteristic is captured separately by the and properties. + +Note that data access to remote servers (for example, using a to connect to another SQL Server instance) is available in user-defined functions. However, you must still honor the declaration. If the common language runtime (CLR) function is marked as deterministic, it should not cause side-effects in the remote server. While side-effects against the context connection are restricted, SQL Server will not enforce the restriction for side-effects over remote connections. + +The default value of this attribute is `false`. + +Do not mark a function as deterministic if the function does not always produce the same output values, given the same input values and the same database state. Marking a function as deterministic when the function is not truly deterministic can result in corrupted indexed views and computed columns. + +]]> + + + + Indicates whether the function involves imprecise computations, such as floating point operations. + + if the function involves precise computations; otherwise . + + + + + + The name under which the function should be registered in SQL Server. + A value representing the name under which the function should be registered. + + + + + + Indicates whether the function requires access to data stored in the system catalogs or virtual system tables of SQL Server. + + .: Does not access system data. .: Only reads system data. + + . + +]]> + + + + A string that represents the table definition of the results, if the method is used as a table-valued function (TVF). + A value representing the table definition of the results. + + + + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/SqlMethodAttribute.xml b/doc/snippets/Microsoft.SqlServer.Server/SqlMethodAttribute.xml new file mode 100644 index 0000000000..55a9858ded --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/SqlMethodAttribute.xml @@ -0,0 +1,68 @@ + + + + + Indicates the determinism and data access properties of a method or property on a user-defined type (UDT). The properties on the attribute reflect the physical characteristics that are used when the type is registered with SQL Server. + + should be used on the setter or the getter directly. + + inherits from a , so inherits the `FillRowMethodName` and `TableDefinition` fields from . Note that it is not possible to write a table-valued method, although the names of these fields might suggest that it is possible. + +## Examples +The following example shows a UDT method that is attributed to indicate that the method will not be invoked on null instances of the type, that the method will not change the state of the type, and that the method will not be called when `null` parameters are supplied to the method invocation. + +[!code-csharp[SqlMethodAttribute Samples#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/csharp/SqlMethod.cs#1)] + +]]> + + + + An attribute on a user-defined type (UDT), used to indicate the determinism and data access properties of a method or a property on a UDT. + To be added. + + + Indicates whether SQL Server should invoke the method on null instances. + if SQL Server should invoke the method on null instances; otherwise, . If the method cannot be invoked (because of an attribute on the method), the SQL Server is returned. + + + + + + Indicates whether a method on a user-defined type (UDT) is a mutator. + if the method is a mutator; otherwise . + + property is set to `true` and the return type of the method is `void`, SQL Server marks the method as a mutator. A mutator method is one that causes a state change in the UDT instance. Mutator methods can be called in assignment statements or data modification statements, but cannot be used in queries. If a method is marked as a mutator but does not return void, then CREATE TYPE does not fail with an error. Even though a returned value other than `void` does not raise an error, the returned value is not accessible and cannot be used. + +The default value of the property is `false`. + +A property can be a mutator if is used on the setter and is set to `true`. However, a property setter is implicitly treated as a mutator, so it is not necessary to set the property of the to `true`. + +]]> + + + + Indicates whether the method on a user-defined type (UDT) is called when input arguments are specified in the method invocation. + if the method is called when input arguments are specified in the method invocation; if the method returns a value when any of its input parameters are . If the method cannot be invoked (because of an attribute on the method), the SQL Server is returned. + + property is `true`. + +]]> + + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/SqlUserDefinedAggregateAttribute.xml b/doc/snippets/Microsoft.SqlServer.Server/SqlUserDefinedAggregateAttribute.xml new file mode 100644 index 0000000000..a0a5eafe1b --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/SqlUserDefinedAggregateAttribute.xml @@ -0,0 +1,134 @@ + + + + + Indicates that the type should be registered as a user-defined aggregate. The properties on the attribute reflect the physical attributes used when the type is registered with SQL Server. This class cannot be inherited. + + custom attribute. Every user-defined aggregate must be annotated with this attribute. + +See "CLR User-Defined Aggregates" in SQL Server 2005 Books Online for more information on user-defined aggregates and examples. + +## Examples +The following example shows the attribute for a user-defined aggregate. The aggregate uses custom serialization, has a maximum size of 8000 bytes when serialized, and is invariant to nulls, duplicates, and order. + +[!code-csharp[SqlUserDefinedAggregateAttribute Samples#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedAggregateAttribute_Sample.cs#1)] +[!code-vb[SqlUserDefinedAggregateAttribute Samples#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedAggregateAttribute_Sample.vb#1)] + +]]> + + + + One of the values representing the serialization format of the aggregate. + A required attribute on a user-defined aggregate, used to indicate that the given type is a user-defined aggregate and the storage format of the user-defined aggregate. + + + The serialization format as a . + A representing the serialization format. + + + + + + Indicates whether the aggregate is invariant to duplicates. + if the aggregate is invariant to duplicates; otherwise . + + + + + + Indicates whether the aggregate is invariant to nulls. + if the aggregate is invariant to nulls; otherwise . + + + + + + Indicates whether the aggregate is invariant to order. + if the aggregate is invariant to order; otherwise . + + + + + + Indicates whether the aggregate returns if no values have been accumulated. + if the aggregate returns if no values have been accumulated; otherwise . + + + + + + The maximum size, in bytes, of the aggregate instance. + An value representing the maximum size of the aggregate instance. + + property with the UserDefined serialization . + +The maximum allowed value for this property is specified by the field. + +The maximum size allowed is 2 gigabytes (GB). You can specify a number from 1 to 8000 bytes, or -1 to represent a value larger than 8000 bytes, up to 2 gigabytes. + +For an aggregate with user-defined serialization specified, refers to the total size of the serialized data. Consider an aggregate serializing a string of 10 characters (). When the string is serialized using a , the total size of the serialized string is 22 bytes: 2 bytes per Unicode UTF-16 character, multiplied by the maximum number of characters, plus 2 control bytes of overhead incurred from serializing a binary stream. So, when determining the value of , the total size of the serialized data must be considered: the size of the data serialized in binary form plus the overhead incurred by serialization. + +]]> + + + + The maximum size, in bytes, required to store the state of this aggregate instance during computation. + + value representing the maximum size of the aggregate instance. + +]]> + + + + The name of the aggregate. + A value representing the name of the aggregate. + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/SqlUserDefinedTypeAttribute.xml b/doc/snippets/Microsoft.SqlServer.Server/SqlUserDefinedTypeAttribute.xml new file mode 100644 index 0000000000..ffd70496cc --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/SqlUserDefinedTypeAttribute.xml @@ -0,0 +1,139 @@ + + + + + Used to mark a type definition in an assembly as a user-defined type (UDT) in SQL Server. The properties on the attribute reflect the physical characteristics used when the type is registered with SQL Server. This class cannot be inherited. + + custom attribute. Every UDT must be annotated with this attribute. See [CLR User-Defined Types](https://go.microsoft.com/fwlink/?LinkId=128028) for more information about UDTs, including an example of a UDT. + +## Examples +The following example shows the `UserDefinedType` attribute of the Point UDT. The UDT is byte-ordered, is named "Point", has a validation method named "ValidatePoint", and uses the native serialization format. + +[!code-csharp[SqlUserDefinedTypeAttribute Samples#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/csharp/DataWorks_SqlUserDefinedTypeAttribute_Sample.cs#1)] +[!code-vb[SqlUserDefinedTypeAttribute Samples#1](~/../sqlclient/doc/samples/Microsoft.SqlServer.Server/visualbasic/DataWorks_SqlUserDefinedTypeAttribute_Sample.vb#1)] + +]]> + + + + One of the values representing the serialization format of the type. + A required attribute on a user-defined type (UDT), used to confirm that the given type is a UDT and to indicate the storage format of the UDT. + + + + + + The serialization format as a . + A value representing the serialization format. + + + Indicates whether the user-defined type is byte ordered. + + if the user-defined type is byte ordered; otherwise . + + property in effect guarantees that the serialized binary data can be used for semantic ordering of the information. Thus, each instance of a byte-ordered UDT object can only have one serialized representation. When a comparison operation is performed in SQL Server on the serialized bytes, its results should be the same as if the same comparison operation had taken place in managed code. + +The following features are supported when is set to `true`: + +- The ability to create indexes on columns of this type. + +- The ability to create primary and foreign keys as well as CHECK and UNIQUE constraints on columns of this type. + +- The ability to use Transact-SQL ORDER BY, GROUP BY, and PARTITION BY clauses. In these cases, the binary representation of the type is used to determine the order. + +- The ability to use comparison operators in Transact-SQL statements. + +- The ability to persist computed columns of this type. + +Note that both the `Native` and `UserDefined` serialization formats support the following comparison operators when is set to `true`: + +- Equal to (=) + +- Not equal to (!=) + +- Greater than (>) + +- Less than (\<) + +- Greater than or equal to (>=) + +- Less than or equal to (<=) + +]]> + + + + Indicates whether all instances of this user-defined type are the same length. + + if all instances of this type are the same length; otherwise . + + + . This attribute is only relevant for UDTs with `UserDefined` serialization . + +]]> + + + + The maximum size of the instance, in bytes. + An value representing the maximum size of the instance. + + property with the `UserDefined` serialization . + +When connecting to SQL Server 2005 or earlier, must be between 1 and 8000. + +When connecting to SQL Server 2008 or later, set between 1 and 8000, for a type whose instances are always 8,000 bytes or less. For types that can have instances larger than 8000, specify -1. + +For a UDT with user-defined serialization specified, refers to the total size of the UDT in its serialized form as defined by the user. Consider a UDT with a property of a string of 10 characters (). When the UDT is serialized using a , the total size of the serialized string is 22 bytes: 2 bytes per Unicode UTF-16 character, multiplied by the maximum number of characters, plus 2 control bytes of overhead incurred from serializing a binary stream. So, when determining the value of , the total size of the serialized UDT must be considered: the size of the data serialized in binary form plus the overhead incurred by serialization. + +This property should not be used with `Native` serialization . + +]]> + + + + The SQL Server name of the user-defined type. + A value representing the SQL Server name of the user-defined type. + + property is not used within SQL Server, but is used by the Microsoft Visual Studio .NET Integrated Development Environment (IDE). + +]]> + + + + The name of the method used to validate instances of the user-defined type. + A representing the name of the method used to validate instances of the user-defined type. + + + + + + diff --git a/doc/snippets/Microsoft.SqlServer.Server/SystemDataAccessKind.xml b/doc/snippets/Microsoft.SqlServer.Server/SystemDataAccessKind.xml new file mode 100644 index 0000000000..93f80783d0 --- /dev/null +++ b/doc/snippets/Microsoft.SqlServer.Server/SystemDataAccessKind.xml @@ -0,0 +1,26 @@ + + + + + Describes the type of access to system data for a user-defined method or function. + + and to indicate what type of access to system data the method or function has. + +Note that methods and functions are not allowed to make changes to the database, so the options for this enumeration are `None` (meaning no data-access performed by the method or function) and `Read` (meaning that the method or function performs read-only data-access operations, such as executing SELECT statements). + + ]]> + + + + The method or function does not access system data. + + + The method or function reads system data. + + + diff --git a/src/Microsoft.SqlServer.Server/IBinarySerialize.cs b/src/Microsoft.SqlServer.Server/IBinarySerialize.cs index 1e844f0300..a975887161 100644 --- a/src/Microsoft.SqlServer.Server/IBinarySerialize.cs +++ b/src/Microsoft.SqlServer.Server/IBinarySerialize.cs @@ -6,15 +6,15 @@ namespace Microsoft.SqlServer.Server { - /// + /// // This interface is used by types that want full control over the // binary serialization format. public interface IBinarySerialize { - /// + /// // Read from the specified binary reader. void Read(BinaryReader r); - /// + /// // Write to the specified binary writer. void Write(BinaryWriter w); } diff --git a/src/Microsoft.SqlServer.Server/InvalidUdtException.cs b/src/Microsoft.SqlServer.Server/InvalidUdtException.cs index 4d58ed1f27..395b02af61 100644 --- a/src/Microsoft.SqlServer.Server/InvalidUdtException.cs +++ b/src/Microsoft.SqlServer.Server/InvalidUdtException.cs @@ -7,7 +7,7 @@ namespace Microsoft.SqlServer.Server { - /// + /// [Serializable] public sealed class InvalidUdtException : SystemException { @@ -32,14 +32,14 @@ private InvalidUdtException(SerializationInfo si, StreamingContext sc) : base(si { } - /// + /// [System.Security.Permissions.SecurityPermissionAttribute(System.Security.Permissions.SecurityAction.LinkDemand, Flags = System.Security.Permissions.SecurityPermissionFlag.SerializationFormatter)] public override void GetObjectData(SerializationInfo si, StreamingContext context) { base.GetObjectData(si, context); } - /// + /// public static InvalidUdtException Create(Type udtType, string resourceReason = "SqlUdtReason_NoUdtAttribute") { string reason = StringsHelper.GetString(resourceReason); diff --git a/src/Microsoft.SqlServer.Server/SqlFacetAttribute.cs b/src/Microsoft.SqlServer.Server/SqlFacetAttribute.cs index fd20dbf95a..ba5cd82683 100644 --- a/src/Microsoft.SqlServer.Server/SqlFacetAttribute.cs +++ b/src/Microsoft.SqlServer.Server/SqlFacetAttribute.cs @@ -6,42 +6,42 @@ namespace Microsoft.SqlServer.Server { - /// + /// [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property | AttributeTargets.ReturnValue | AttributeTargets.Parameter, AllowMultiple = false, Inherited = false)] public class SqlFacetAttribute : Attribute { - /// + /// public SqlFacetAttribute() { } - /// + /// public bool IsFixedLength { get; set; } - /// + /// public int MaxSize { get; set; } - /// + /// public int Precision { get; set; } - /// + /// public int Scale { get; set; } - /// + /// public bool IsNullable { get; diff --git a/src/Microsoft.SqlServer.Server/SqlFunctionAttribute.cs b/src/Microsoft.SqlServer.Server/SqlFunctionAttribute.cs index 53bdf15d02..4d735cd77f 100644 --- a/src/Microsoft.SqlServer.Server/SqlFunctionAttribute.cs +++ b/src/Microsoft.SqlServer.Server/SqlFunctionAttribute.cs @@ -6,27 +6,27 @@ namespace Microsoft.SqlServer.Server { - /// + /// [Serializable] public enum DataAccessKind { - /// + /// None = 0, - /// + /// Read = 1, } - /// + /// [Serializable] public enum SystemDataAccessKind { - /// + /// None = 0, - /// + /// Read = 1, } - /// + /// // sql specific attribute [AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = false), Serializable] public class SqlFunctionAttribute : Attribute @@ -39,7 +39,7 @@ public class SqlFunctionAttribute : Attribute private string _tableDefinition; private string _fillRowMethodName; - /// + /// public SqlFunctionAttribute() { // default values @@ -52,49 +52,49 @@ public SqlFunctionAttribute() _fillRowMethodName = null; } - /// + /// public bool IsDeterministic { get => _isDeterministic; set => _isDeterministic = value; } - /// + /// public DataAccessKind DataAccess { get => _dataAccess; set => _dataAccess = value; } - /// + /// public SystemDataAccessKind SystemDataAccess { get => _systemDataAccess; set => _systemDataAccess = value; } - /// + /// public bool IsPrecise { get => _isPrecise; set => _isPrecise = value; } - /// + /// public string Name { get => _name; set => _name = value; } - /// + /// public string TableDefinition { get => _tableDefinition; set => _tableDefinition = value; } - /// + /// public string FillRowMethodName { get => _fillRowMethodName; diff --git a/src/Microsoft.SqlServer.Server/SqlMethodAttribute.cs b/src/Microsoft.SqlServer.Server/SqlMethodAttribute.cs index cd94a4f28b..a28afa2251 100644 --- a/src/Microsoft.SqlServer.Server/SqlMethodAttribute.cs +++ b/src/Microsoft.SqlServer.Server/SqlMethodAttribute.cs @@ -6,7 +6,7 @@ namespace Microsoft.SqlServer.Server { - /// + /// [AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = false), Serializable] public sealed class SqlMethodAttribute : SqlFunctionAttribute { @@ -14,7 +14,7 @@ public sealed class SqlMethodAttribute : SqlFunctionAttribute private bool _isMutator; private bool _shouldInvokeIfReceiverIsNull; - /// + /// public SqlMethodAttribute() { // default values @@ -23,21 +23,21 @@ public SqlMethodAttribute() _shouldInvokeIfReceiverIsNull = false; } - /// + /// public bool OnNullCall { get => _isCalledOnNullInputs; set => _isCalledOnNullInputs = value; } - /// + /// public bool IsMutator { get => _isMutator; set => _isMutator = value; } - /// + /// public bool InvokeIfReceiverIsNull { get => _shouldInvokeIfReceiverIsNull; diff --git a/src/Microsoft.SqlServer.Server/SqlUserDefinedAggregateAttribute.cs b/src/Microsoft.SqlServer.Server/SqlUserDefinedAggregateAttribute.cs index 8058795d17..6e3e949f16 100644 --- a/src/Microsoft.SqlServer.Server/SqlUserDefinedAggregateAttribute.cs +++ b/src/Microsoft.SqlServer.Server/SqlUserDefinedAggregateAttribute.cs @@ -7,7 +7,7 @@ namespace Microsoft.SqlServer.Server { - /// + /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct, AllowMultiple = false, Inherited = false)] public sealed class SqlUserDefinedAggregateAttribute : Attribute { @@ -19,11 +19,11 @@ public sealed class SqlUserDefinedAggregateAttribute : Attribute private Format _format; private string _name; - /// + /// // The maximum value for the maxbytesize field, in bytes. public const int MaxByteSizeValue = 8000; - /// + /// // A required attribute on all UD Aggs, used to indicate that the // given type is a UD Agg, and its storage format. public SqlUserDefinedAggregateAttribute(Format format) @@ -41,7 +41,7 @@ public SqlUserDefinedAggregateAttribute(Format format) } } - /// + /// // The maximum size of this instance, in bytes. Does not have to be // specified for Native format serialization. The maximum value // for this property is specified by MaxByteSizeValue. @@ -62,7 +62,7 @@ public int MaxByteSize } } - /// + /// public bool IsInvariantToDuplicates { get @@ -75,7 +75,7 @@ public bool IsInvariantToDuplicates } } - /// + /// public bool IsInvariantToNulls { get @@ -88,7 +88,7 @@ public bool IsInvariantToNulls } } - /// + /// public bool IsInvariantToOrder { get @@ -101,7 +101,7 @@ public bool IsInvariantToOrder } } - /// + /// public bool IsNullIfEmpty { get @@ -114,11 +114,11 @@ public bool IsNullIfEmpty } } - /// + /// // The on-disk format for this type. public Format Format => _format; - /// + /// public string Name { get diff --git a/src/Microsoft.SqlServer.Server/SqlUserDefinedTypeAttribute.cs b/src/Microsoft.SqlServer.Server/SqlUserDefinedTypeAttribute.cs index 4e55366394..0f24b89150 100644 --- a/src/Microsoft.SqlServer.Server/SqlUserDefinedTypeAttribute.cs +++ b/src/Microsoft.SqlServer.Server/SqlUserDefinedTypeAttribute.cs @@ -7,18 +7,18 @@ namespace Microsoft.SqlServer.Server { - /// + /// public enum Format { - /// + /// Unknown = 0, - /// + /// Native = 1, - /// + /// UserDefined = 2, } - /// + /// // This custom attribute indicates that the given type is // a SqlServer udt. The properties on the attribute reflect the // physical attributes that will be used when the type is registered @@ -36,7 +36,7 @@ public sealed class SqlUserDefinedTypeAttribute : Attribute internal const int YukonMaxByteSizeValue = 8000; private string _validationMethodName = null; - /// + /// // A required attribute on all udts, used to indicate that the // given type is a udt, and its storage format. public SqlUserDefinedTypeAttribute(Format format) @@ -54,7 +54,7 @@ public SqlUserDefinedTypeAttribute(Format format) } } - /// + /// // The maximum size of this instance, in bytes. Does not have to be // specified for Native serialization. The maximum value // for this property is specified by MaxByteSizeValue. @@ -74,7 +74,7 @@ public int MaxByteSize } } - /// + /// // Are all instances of this udt the same size on disk? public bool IsFixedLength { @@ -88,7 +88,7 @@ public bool IsFixedLength } } - /// + /// // Is this type byte ordered, i.e. is the on disk representation // consistent with the ordering semantics for this type? // If true, the binary representation of the type will be used @@ -106,11 +106,11 @@ public bool IsByteOrdered } } - /// + /// // The on-disk format for this type. public Format Format => _format; - /// + /// // An Optional method used to validate this UDT public string ValidationMethodName { @@ -124,7 +124,7 @@ public string ValidationMethodName } } - /// + /// public string Name { get diff --git a/src/Microsoft.SqlServer.Server/TypeForwards.cs b/src/Microsoft.SqlServer.Server/TypeForwards.cs index 9b9c27afdd..8f1161bce9 100644 --- a/src/Microsoft.SqlServer.Server/TypeForwards.cs +++ b/src/Microsoft.SqlServer.Server/TypeForwards.cs @@ -1,4 +1,7 @@ - +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. +// See the LICENSE file in the project root for more information. + [assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(Microsoft.SqlServer.Server.IBinarySerialize))] [assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(Microsoft.SqlServer.Server.InvalidUdtException))] [assembly: System.Runtime.CompilerServices.TypeForwardedTo(typeof(Microsoft.SqlServer.Server.Format))]