Skip to content

Commit bad1143

Browse files
yv989cyv989c
committed
refactor: rename SerializationOptions to SqlServerSerialization and docs
1 parent 4e77b35 commit bad1143

File tree

10 files changed

+99
-97
lines changed

10 files changed

+99
-97
lines changed

‎benchmarks/QueryableValues.SqlServer.Benchmarks/ContainsBenchmarks.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,8 @@ public void GlobalSetup()
7878
{
7979
Console.WriteLine("Initializing...");
8080

81-
var dbContextXml = new MyDbContext(SerializationOptions.UseXml);
82-
var dbContextJson = new MyDbContext(SerializationOptions.UseJson);
81+
var dbContextXml = new MyDbContext(SqlServerSerialization.UseXml);
82+
var dbContextJson = new MyDbContext(SqlServerSerialization.UseJson);
8383

8484
#region Init db
8585
{

‎benchmarks/QueryableValues.SqlServer.Benchmarks/MyDbContext.cs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,22 @@ namespace QueryableValues.SqlServer.Benchmarks
66
{
77
public class MyDbContext : DbContext
88
{
9-
private readonly SerializationOptions _serializationOptions;
9+
private readonly SqlServerSerialization _serializationOption;
1010

1111
public DbSet<Int32Entity> Int32Entities { get; set; } = default!;
1212
public DbSet<GuidEntity> GuidEntities { get; set; } = default!;
1313
public DbSet<StringEntity> StringEntities { get; set; } = default!;
1414

15-
public MyDbContext(SerializationOptions serializationOptions)
15+
public MyDbContext(SqlServerSerialization serializationOption)
1616
{
17-
_serializationOptions = serializationOptions;
17+
_serializationOption = serializationOption;
1818
}
1919

2020
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
2121
{
2222
optionsBuilder.UseSqlServer(
2323
@"Server=.\SQLEXPRESS;Integrated Security=true;Database=QueryableValuesBenchmarks;Encrypt=False;",
24-
builder => builder.UseQueryableValues(options => options.Serialization(_serializationOptions))
24+
builder => builder.UseQueryableValues(options => options.Serialization(_serializationOption))
2525
);
2626
}
2727

‎src/QueryableValues.SqlServer/QueryableValuesSqlServerOptions.cs‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ public sealed class QueryableValuesSqlServerOptions
1010
{
1111
internal bool WithUseSelectTopOptimization { get; private set; } = true;
1212
internal bool WithUseDeferredEnumeration { get; private set; } = true;
13-
internal SerializationOptions WithSerializationOptions { get; private set; } = SerializationOptions.Auto;
13+
internal SqlServerSerialization WithSerializationOption { get; private set; } = SqlServerSerialization.Auto;
1414

1515
/// <summary>
1616
/// When possible, uses a <c>TOP(n)</c> clause in the underlying <c>SELECT</c> statement to assist SQL Server memory grant estimation. The default is <see langword="true"/>.
@@ -28,19 +28,19 @@ public QueryableValuesSqlServerOptions UseSelectTopOptimization(bool useSelectTo
2828
}
2929

3030
/// <summary>
31-
/// Configures serialization options. The default is <see cref="SerializationOptions.Auto"/>.
31+
/// Configures the serialization format to be used when sending data to SQL Server. The default is <see cref="SqlServerSerialization.Auto"/>.
3232
/// </summary>
33-
/// <param name="options">Serialization options.</param>
33+
/// <param name="option">Serialization options.</param>
3434
/// <returns>The same <see cref="QueryableValuesSqlServerOptions"/> instance so subsequent configurations can be chained.</returns>
35-
public QueryableValuesSqlServerOptions Serialization(SerializationOptions options = SerializationOptions.Auto)
35+
public QueryableValuesSqlServerOptions Serialization(SqlServerSerialization option = SqlServerSerialization.Auto)
3636
{
37-
if (Enum.IsDefined(typeof(SerializationOptions), options))
37+
if (Enum.IsDefined(typeof(SqlServerSerialization), option))
3838
{
39-
WithSerializationOptions = options;
39+
WithSerializationOption = option;
4040
}
4141
else
4242
{
43-
throw new ArgumentOutOfRangeException(nameof(options));
43+
throw new ArgumentOutOfRangeException(nameof(option));
4444
}
4545

4646
return this;

‎src/QueryableValues.SqlServer/SerializationOptions.cs‎

Lines changed: 0 additions & 41 deletions
This file was deleted.

‎src/QueryableValues.SqlServer/SqlServer/JsonSupportConnectionInterceptor.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ private static string GetKey(DbConnection connection)
4444
private bool MustDetect(DbConnection connection)
4545
{
4646
return
47-
_options.WithSerializationOptions == SerializationOptions.Auto &&
47+
_options.WithSerializationOption == SqlServerSerialization.Auto &&
4848
!ConnectionStringJsonSupport.ContainsKey(GetKey(connection));
4949
}
5050

‎src/QueryableValues.SqlServer/SqlServer/QueryableFactoryFactory.cs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@ public QueryableFactoryFactory(IServiceProvider serviceProvider, ExtensionOption
1818

1919
public IQueryableFactory Create(DbContext dbContext)
2020
{
21-
var useJson = _options.WithSerializationOptions switch
21+
var useJson = _options.WithSerializationOption switch
2222
{
23-
SerializationOptions.Auto => JsonSupportConnectionInterceptor.HasJsonSupport(dbContext).GetValueOrDefault(),
24-
SerializationOptions.UseJson => true,
25-
SerializationOptions.UseXml => false,
23+
SqlServerSerialization.Auto => JsonSupportConnectionInterceptor.HasJsonSupport(dbContext).GetValueOrDefault(),
24+
SqlServerSerialization.UseJson => true,
25+
SqlServerSerialization.UseXml => false,
2626
_ => throw new NotImplementedException(),
2727
};
2828

‎src/QueryableValues.SqlServer/SqlServerSerialization.cs‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
#if EFCORE
2+
namespace BlazarTech.QueryableValues
3+
{
4+
/// <summary>
5+
/// Specifies the serialization format to be used when sending data to SQL Server.
6+
/// </summary>
7+
public enum SqlServerSerialization
8+
{
9+
/// <summary>
10+
/// Automatically chooses between JSON and XML serialization based on server and database compatibility.
11+
/// </summary>
12+
/// <remarks>
13+
/// <para>
14+
/// This option may cause an additional round-trip to the database to check for JSON compatibility,
15+
/// but only once per unique connection string for the life of the process. If JSON serialization is not supported, XML is used instead.
16+
/// </para>
17+
/// <para>
18+
/// Caveat: If the very first query sent to the server is a QueryableValues enabled one, it will use XML and then switch to JSON (if supported) afterward.
19+
/// </para>
20+
/// </remarks>
21+
Auto = 0,
22+
23+
/// <summary>
24+
/// Uses the JSON serializer for better performance.
25+
/// </summary>
26+
/// <remarks>
27+
/// <para>
28+
/// Using JSON is faster than XML, but requires SQL Server 2016 or newer and a database compatibility level of 130 or higher.<br/>
29+
/// More info: <see href="https://learn.microsoft.com/en-us/sql/t-sql/functions/openjson-transact-sql"/>.
30+
/// </para>
31+
/// <para>
32+
/// <b>WARNING:</b> If JSON serialization is not supported, an error will occur at runtime.
33+
/// </para>
34+
/// </remarks>
35+
UseJson = 1,
36+
37+
/// <summary>
38+
/// Uses the XML serializer, which is compatible with all supported versions of SQL Server to date.
39+
/// </summary>
40+
UseXml = 2
41+
}
42+
}
43+
#endif

‎tests/QueryableValues.SqlServer.Tests/Integration/ComplexTypeTests.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -802,7 +802,7 @@ public class JsonComplexTypeTests : ComplexTypeTests
802802
{
803803
public JsonComplexTypeTests(DbContextFixture contextFixture) : base(contextFixture)
804804
{
805-
_db.Options.Serialization(SerializationOptions.UseJson);
805+
_db.Options.Serialization(SqlServerSerialization.UseJson);
806806
}
807807
}
808808

@@ -811,7 +811,7 @@ public class XmlComplexTypeTests : ComplexTypeTests
811811
{
812812
public XmlComplexTypeTests(DbContextFixture contextFixture) : base(contextFixture)
813813
{
814-
_db.Options.Serialization(SerializationOptions.UseXml);
814+
_db.Options.Serialization(SqlServerSerialization.UseXml);
815815
}
816816
}
817817
}

‎tests/QueryableValues.SqlServer.Tests/Integration/InfrastructureTests.cs‎

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -56,22 +56,22 @@ public void OnlyWorksOnDbContext()
5656

5757
#if !EFCORE3
5858
[Theory]
59-
[InlineData(SerializationOptions.UseJson)]
60-
[InlineData(SerializationOptions.UseXml)]
61-
public async Task MustControlSelectTopOptimization(SerializationOptions serializationOptions)
59+
[InlineData(SqlServerSerialization.UseJson)]
60+
[InlineData(SqlServerSerialization.UseXml)]
61+
public async Task MustControlSelectTopOptimization(SqlServerSerialization serializationOption)
6262
{
6363
var services = new ServiceCollection();
6464
services.AddDbContext<MyDbContext>();
6565
services.AddDbContext<NotOptimizedMyDbContext>();
6666
using var serviceProvider = services.BuildServiceProvider();
6767

6868
var optimizedDb = serviceProvider.GetRequiredService<MyDbContext>();
69-
optimizedDb.Options.Serialization(serializationOptions);
69+
optimizedDb.Options.Serialization(serializationOption);
7070
Assert.True(await isOptimizationEnabledSimpleType(optimizedDb));
7171
Assert.True(await isOptimizationEnabledComplexType(optimizedDb));
7272

7373
var notOptimizedDb = serviceProvider.GetRequiredService<NotOptimizedMyDbContext>();
74-
notOptimizedDb.Options.Serialization(serializationOptions);
74+
notOptimizedDb.Options.Serialization(serializationOption);
7575
Assert.False(await isOptimizationEnabledComplexType(notOptimizedDb));
7676
Assert.False(await isOptimizationEnabledSimpleType(notOptimizedDb));
7777

@@ -104,17 +104,17 @@ async Task<bool> isOptimizationEnabledComplexType(MyDbContextBase db)
104104
}
105105

106106
[Theory]
107-
[InlineData(SerializationOptions.UseJson)]
108-
[InlineData(SerializationOptions.UseXml)]
109-
public async Task MustControlSerializationFormat(SerializationOptions serializationOptions)
107+
[InlineData(SqlServerSerialization.UseJson)]
108+
[InlineData(SqlServerSerialization.UseXml)]
109+
public async Task MustControlSerializationFormat(SqlServerSerialization serializationOption)
110110
{
111111
var services = new ServiceCollection();
112112
services.AddDbContext<MyDbContext>();
113113

114114
using var serviceProvider = services.BuildServiceProvider();
115115

116116
var db = serviceProvider.GetRequiredService<MyDbContext>();
117-
db.Options.Serialization(serializationOptions);
117+
db.Options.Serialization(serializationOption);
118118

119119
Assert.True(await isRightSerializationFormatSimpleType(db));
120120
Assert.True(await isRightSerializationFormatComplexType(db));
@@ -148,11 +148,11 @@ async Task<bool> isRightSerializationFormatComplexType(MyDbContextBase db)
148148

149149
bool isRightFormat(string logEntry)
150150
{
151-
switch (serializationOptions)
151+
switch (serializationOption)
152152
{
153-
case SerializationOptions.UseJson:
153+
case SqlServerSerialization.UseJson:
154154
return logEntry.Contains("OPENJSON(");
155-
case SerializationOptions.UseXml:
155+
case SqlServerSerialization.UseXml:
156156
return logEntry.Contains(".nodes(");
157157
default:
158158
throw new NotImplementedException();
@@ -161,22 +161,22 @@ bool isRightFormat(string logEntry)
161161
}
162162

163163
[Theory]
164-
[InlineData(SerializationOptions.Auto)]
165-
[InlineData(SerializationOptions.UseJson)]
166-
[InlineData(SerializationOptions.UseXml)]
167-
public async Task JsonSupportDetection(SerializationOptions serializationOptions)
164+
[InlineData(SqlServerSerialization.Auto)]
165+
[InlineData(SqlServerSerialization.UseJson)]
166+
[InlineData(SqlServerSerialization.UseXml)]
167+
public async Task JsonSupportDetection(SqlServerSerialization serializationOption)
168168
{
169169
var services = new ServiceCollection();
170170
services.AddDbContext<MyDbContext>();
171171

172172
using var serviceProvider = services.BuildServiceProvider();
173173

174174
var db = serviceProvider.GetRequiredService<MyDbContext>();
175-
db.Options.Serialization(serializationOptions);
175+
db.Options.Serialization(serializationOption);
176176

177-
switch (serializationOptions)
177+
switch (serializationOption)
178178
{
179-
case SerializationOptions.Auto:
179+
case SqlServerSerialization.Auto:
180180
{
181181
forceJsonDetection();
182182
Assert.Null(JsonSupportConnectionInterceptor.HasJsonSupport(db));
@@ -189,8 +189,8 @@ public async Task JsonSupportDetection(SerializationOptions serializationOptions
189189
Assert.True(JsonSupportConnectionInterceptor.HasJsonSupport(db));
190190
}
191191
break;
192-
case SerializationOptions.UseJson:
193-
case SerializationOptions.UseXml:
192+
case SqlServerSerialization.UseJson:
193+
case SqlServerSerialization.UseXml:
194194
{
195195
forceJsonDetection();
196196
Assert.Null(JsonSupportConnectionInterceptor.HasJsonSupport(db));
@@ -210,30 +210,30 @@ void forceJsonDetection()
210210
#endif
211211

212212
[Theory]
213-
[InlineData(SerializationOptions.UseJson)]
214-
[InlineData(SerializationOptions.UseXml)]
215-
[InlineData(SerializationOptions.Auto)]
216-
public void MustCreateQueryableFactory(SerializationOptions serializationOptions)
213+
[InlineData(SqlServerSerialization.UseJson)]
214+
[InlineData(SqlServerSerialization.UseXml)]
215+
[InlineData(SqlServerSerialization.Auto)]
216+
public void MustCreateQueryableFactory(SqlServerSerialization serializationOption)
217217
{
218218
var services = new ServiceCollection();
219219
services.AddDbContext<MyDbContext>();
220220

221221
using var serviceProvider = services.BuildServiceProvider();
222222

223223
var dbContext = serviceProvider.GetRequiredService<MyDbContext>();
224-
dbContext.Options.Serialization(serializationOptions);
224+
dbContext.Options.Serialization(serializationOption);
225225

226226
var queryableFactory = dbContext.GetService<QueryableFactoryFactory>().Create(dbContext);
227227

228228
Assert.NotNull(queryableFactory);
229229

230-
switch (serializationOptions)
230+
switch (serializationOption)
231231
{
232-
case SerializationOptions.UseJson:
233-
case SerializationOptions.Auto:
232+
case SqlServerSerialization.UseJson:
233+
case SqlServerSerialization.Auto:
234234
Assert.IsType<JsonQueryableFactory>(queryableFactory);
235235
break;
236-
case SerializationOptions.UseXml:
236+
case SqlServerSerialization.UseXml:
237237
Assert.IsType<XmlQueryableFactory>(queryableFactory);
238238
break;
239239
default:

0 commit comments

Comments
 (0)