From 263b7928b18af8f219fc0baea1ca0460e560d6a8 Mon Sep 17 00:00:00 2001 From: Arthur Vickers Date: Thu, 18 Jun 2020 15:58:59 -0700 Subject: [PATCH] Document some internal constructors Part of #16708 --- .../Query/Internal/SqlParameterExpression.cs | 17 +++++++++++------ ...RelationalSqlTranslatingExpressionVisitor.cs | 1 - .../Query/SqlExpressions/ColumnExpression.cs | 1 - .../SqlExpressions/ProjectionExpression.cs | 8 ++++---- .../SqlExpressions/SqlParameterExpression.cs | 6 +++--- .../Query/SqlExpressions/TableExpression.cs | 7 ++++--- src/EFCore/DbFunctions.cs | 5 +++-- src/EFCore/EF.cs | 3 ++- test/EFCore.Tests/DbFunctionsTest.cs | 2 +- 9 files changed, 28 insertions(+), 22 deletions(-) diff --git a/src/EFCore.Cosmos/Query/Internal/SqlParameterExpression.cs b/src/EFCore.Cosmos/Query/Internal/SqlParameterExpression.cs index d2e1fe6b6b7..b92b6bbedf3 100644 --- a/src/EFCore.Cosmos/Query/Internal/SqlParameterExpression.cs +++ b/src/EFCore.Cosmos/Query/Internal/SqlParameterExpression.cs @@ -16,12 +16,17 @@ namespace Microsoft.EntityFrameworkCore.Cosmos.Query.Internal /// any release. You should only use it directly in your code with extreme caution and knowing that /// doing so can result in application failures when updating to a new Entity Framework Core release. /// - // Class is sealed because there are no public/protected constructors. Can be unsealed if this is changed. public sealed class SqlParameterExpression : SqlExpression { private readonly ParameterExpression _parameterExpression; - internal SqlParameterExpression(ParameterExpression parameterExpression, CoreTypeMapping typeMapping) + /// + /// This is an internal API that supports the Entity Framework Core infrastructure and not subject to + /// the same compatibility standards as public APIs. It may be changed or removed without notice in + /// any release. You should only use it directly in your code with extreme caution and knowing that + /// doing so can result in application failures when updating to a new Entity Framework Core release. + /// + public SqlParameterExpression([NotNull] ParameterExpression parameterExpression, [CanBeNull] CoreTypeMapping typeMapping) : base(parameterExpression.Type, typeMapping) { _parameterExpression = parameterExpression; @@ -78,13 +83,13 @@ protected override void Print(ExpressionPrinter expressionPrinter) /// public override bool Equals(object obj) => obj != null - && (ReferenceEquals(this, obj) - || obj is SqlParameterExpression sqlParameterExpression - && Equals(sqlParameterExpression)); + && (ReferenceEquals(this, obj) + || obj is SqlParameterExpression sqlParameterExpression + && Equals(sqlParameterExpression)); private bool Equals(SqlParameterExpression sqlParameterExpression) => base.Equals(sqlParameterExpression) - && string.Equals(Name, sqlParameterExpression.Name); + && string.Equals(Name, sqlParameterExpression.Name); /// /// This is an internal API that supports the Entity Framework Core infrastructure and not subject to diff --git a/src/EFCore.Relational/Query/RelationalSqlTranslatingExpressionVisitor.cs b/src/EFCore.Relational/Query/RelationalSqlTranslatingExpressionVisitor.cs index d62c17e397c..2ea168af90c 100644 --- a/src/EFCore.Relational/Query/RelationalSqlTranslatingExpressionVisitor.cs +++ b/src/EFCore.Relational/Query/RelationalSqlTranslatingExpressionVisitor.cs @@ -11,7 +11,6 @@ using JetBrains.Annotations; using Microsoft.EntityFrameworkCore.Diagnostics; using Microsoft.EntityFrameworkCore.Infrastructure; -using Microsoft.EntityFrameworkCore.Internal; using Microsoft.EntityFrameworkCore.Metadata; using Microsoft.EntityFrameworkCore.Query.SqlExpressions; using Microsoft.EntityFrameworkCore.Utilities; diff --git a/src/EFCore.Relational/Query/SqlExpressions/ColumnExpression.cs b/src/EFCore.Relational/Query/SqlExpressions/ColumnExpression.cs index ec2c7c6901c..902ee50976e 100644 --- a/src/EFCore.Relational/Query/SqlExpressions/ColumnExpression.cs +++ b/src/EFCore.Relational/Query/SqlExpressions/ColumnExpression.cs @@ -6,7 +6,6 @@ using System.Linq; using System.Linq.Expressions; using Microsoft.EntityFrameworkCore.Metadata; -using Microsoft.EntityFrameworkCore.Metadata.Internal; using Microsoft.EntityFrameworkCore.Storage; using Microsoft.EntityFrameworkCore.Utilities; diff --git a/src/EFCore.Relational/Query/SqlExpressions/ProjectionExpression.cs b/src/EFCore.Relational/Query/SqlExpressions/ProjectionExpression.cs index a5573b02d77..9280bcb0594 100644 --- a/src/EFCore.Relational/Query/SqlExpressions/ProjectionExpression.cs +++ b/src/EFCore.Relational/Query/SqlExpressions/ProjectionExpression.cs @@ -13,11 +13,11 @@ namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions /// An expression that represents a projection in . /// /// - /// This type is typically used by database providers (and other extensions). It is generally - /// not used in application code. + /// This is a simple wrapper around a and an alias. + /// Instances of this type cannot be constructed by application or database provider code. If this is a problem for your + /// application or provider, then please file an issue at https://github.com/dotnet/efcore. /// /// - // Class is sealed because there are no public/protected constructors. Can be unsealed if this is changed. public sealed class ProjectionExpression : Expression, IPrintableExpression { internal ProjectionExpression([NotNull] SqlExpression expression, [NotNull] string alias) @@ -41,7 +41,7 @@ internal ProjectionExpression([NotNull] SqlExpression expression, [NotNull] stri /// public override Type Type => Expression.Type; /// - public sealed override ExpressionType NodeType => ExpressionType.Extension; + public override ExpressionType NodeType => ExpressionType.Extension; /// protected override Expression VisitChildren(ExpressionVisitor visitor) diff --git a/src/EFCore.Relational/Query/SqlExpressions/SqlParameterExpression.cs b/src/EFCore.Relational/Query/SqlExpressions/SqlParameterExpression.cs index 5879fe27a25..34ad94786d1 100644 --- a/src/EFCore.Relational/Query/SqlExpressions/SqlParameterExpression.cs +++ b/src/EFCore.Relational/Query/SqlExpressions/SqlParameterExpression.cs @@ -14,11 +14,11 @@ namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions /// An expression that represents a parameter in a SQL tree. /// /// - /// This type is typically used by database providers (and other extensions). It is generally - /// not used in application code. + /// This is a simple wrapper around a in the SQL tree. + /// Instances of this type cannot be constructed by application or database provider code. If this is a problem for your + /// application or provider, then please file an issue at https://github.com/dotnet/efcore. /// /// - // Class is sealed because there are no public/protected constructors. Can be unsealed if this is changed. public sealed class SqlParameterExpression : SqlExpression { private readonly ParameterExpression _parameterExpression; diff --git a/src/EFCore.Relational/Query/SqlExpressions/TableExpression.cs b/src/EFCore.Relational/Query/SqlExpressions/TableExpression.cs index 94057b07854..91425994e2e 100644 --- a/src/EFCore.Relational/Query/SqlExpressions/TableExpression.cs +++ b/src/EFCore.Relational/Query/SqlExpressions/TableExpression.cs @@ -13,11 +13,11 @@ namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions /// An expression that represents a table or view in a SQL tree. /// /// - /// This type is typically used by database providers (and other extensions). It is generally - /// not used in application code. + /// This is a simple wrapper around a table and schema name. Instances of this type cannot be constructed by + /// application or database provider code. If this is a problem for your application or provider, then please file + /// an issue at https://github.com/dotnet/efcore. /// /// - // Class is sealed because there are no public/protected constructors. Can be unsealed if this is changed. public sealed class TableExpression : TableExpressionBase { internal TableExpression([NotNull] ITableBase table) @@ -44,6 +44,7 @@ protected override void Print(ExpressionPrinter expressionPrinter) /// The name of the table or view. /// public string Name { get; } + /// /// The schema of the table or view. /// diff --git a/src/EFCore/DbFunctions.cs b/src/EFCore/DbFunctions.cs index a4f10e7ae8e..c3bfafe48c3 100644 --- a/src/EFCore/DbFunctions.cs +++ b/src/EFCore/DbFunctions.cs @@ -9,13 +9,14 @@ namespace Microsoft.EntityFrameworkCore /// Provides CLR methods that get translated to database functions when used in LINQ to Entities queries. /// The methods on this class are accessed via . /// - // Class is sealed because there are no public/protected constructors. Can be unsealed if this is changed. public sealed class DbFunctions { - internal DbFunctions() + private DbFunctions() { } + internal static DbFunctions Instance { get; } = new DbFunctions(); + #region Hidden System.Object members /// diff --git a/src/EFCore/EF.cs b/src/EFCore/EF.cs index b7697ebfe16..0be0c3be6c6 100644 --- a/src/EFCore/EF.cs +++ b/src/EFCore/EF.cs @@ -46,6 +46,7 @@ public static TProperty Property( /// Provides CLR methods that get translated to database functions when used in LINQ to Entities queries. /// Calling these methods in other contexts (e.g. LINQ to Objects) will throw a . /// - public static DbFunctions Functions { get; } = new DbFunctions(); + public static DbFunctions Functions + => DbFunctions.Instance; } } diff --git a/test/EFCore.Tests/DbFunctionsTest.cs b/test/EFCore.Tests/DbFunctionsTest.cs index 688bce0b682..07ad4d587b7 100644 --- a/test/EFCore.Tests/DbFunctionsTest.cs +++ b/test/EFCore.Tests/DbFunctionsTest.cs @@ -18,7 +18,7 @@ public void Like_on_client_throws() Assert.Equal( CoreStrings.FunctionOnClient(nameof(DbFunctionsExtensions.Like)), Assert.Throws( - () => new DbFunctions().Like("abc", "abc")).Message); + () => EF.Functions.Like("abc", "abc")).Message); } } }