Add AtTimeZoneExpression and some relevant translations

Closes dotnet#26199
Closes dotnet#26971

All.sln.DotSettings

@@ -285,6 +285,7 @@ The .NET Foundation licenses this file to you under the MIT license.
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=composability/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=composable/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Constructible/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=datetimeoffset/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=doesnt/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=efcore/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=evaluatable/@EntryIndexedValue">True</s:Boolean>

src/EFCore.Relational/Query/QuerySqlGenerator.cs

@@ -895,6 +895,42 @@ protected override Expression VisitIn(InExpression inExpression)
         return inExpression;
     }
 
+    /// <inheritdoc />
+    protected override Expression VisitAtTimeZone(AtTimeZoneExpression atTimeZoneExpression)
+    {
+        var requiresBrackets = RequiresParentheses(atTimeZoneExpression, atTimeZoneExpression.Operand);
+
+        if (requiresBrackets)
+        {
+            _relationalCommandBuilder.Append("(");
+        }
+
+        Visit(atTimeZoneExpression.Operand);
+
+        if (requiresBrackets)
+        {
+            _relationalCommandBuilder.Append(")");
+        }
+
+        _relationalCommandBuilder.Append(" AT TIME ZONE ");
+
+        requiresBrackets = RequiresParentheses(atTimeZoneExpression, atTimeZoneExpression.TimeZone);
+
+        if (requiresBrackets)
+        {
+            _relationalCommandBuilder.Append("(");
+        }
+
+        Visit(atTimeZoneExpression.TimeZone);
+
+        if (requiresBrackets)
+        {
+            _relationalCommandBuilder.Append(")");
+        }
+
+        return atTimeZoneExpression;
+    }
+
     /// <summary>
     ///     Gets a SQL operator for a SQL binary operation.
     /// </summary>
@@ -914,7 +950,7 @@ protected virtual bool RequiresParentheses(SqlExpression outerExpression, SqlExp
     {
         switch (innerExpression)
         {
-            case LikeExpression:
+            case AtTimeZoneExpression or LikeExpression:
                 return true;
 
             case SqlUnaryExpression sqlUnaryExpression:

src/EFCore.Relational/Query/SqlExpressionFactory.cs

@@ -54,6 +54,7 @@ public SqlExpressionFactory(SqlExpressionFactoryDependencies dependencies)
 
         return sqlExpression switch
         {
+            AtTimeZoneExpression e => ApplyTypeMappingOnAtTimeZone(e, typeMapping),
             CaseExpression e => ApplyTypeMappingOnCase(e, typeMapping),
             CollateExpression e => ApplyTypeMappingOnCollate(e, typeMapping),
             DistinctExpression e => ApplyTypeMappingOnDistinct(e, typeMapping),
@@ -69,6 +70,9 @@ public SqlExpressionFactory(SqlExpressionFactoryDependencies dependencies)
         };
     }
 
+    private SqlExpression ApplyTypeMappingOnAtTimeZone(AtTimeZoneExpression atTimeZoneExpression, RelationalTypeMapping? typeMapping)
+        => new AtTimeZoneExpression(atTimeZoneExpression.Operand, atTimeZoneExpression.TimeZone, atTimeZoneExpression.Type, typeMapping);
+
     private SqlExpression ApplyTypeMappingOnLike(LikeExpression likeExpression)
     {
         var inferredTypeMapping = (likeExpression.EscapeChar == null

src/EFCore.Relational/Query/SqlExpressionVisitor.cs

@@ -24,6 +24,9 @@ protected override Expression VisitExtension(Expression extensionExpression)
             case ShapedQueryExpression shapedQueryExpression:
                 return shapedQueryExpression.UpdateQueryExpression(Visit(shapedQueryExpression.QueryExpression));
 
+            case AtTimeZoneExpression atTimeZoneExpression:
+                return VisitAtTimeZone(atTimeZoneExpression);
+
             case CaseExpression caseExpression:
                 return VisitCase(caseExpression);
 
@@ -115,6 +118,14 @@ protected override Expression VisitExtension(Expression extensionExpression)
         return base.VisitExtension(extensionExpression);
     }
 
+
+    /// <summary>
+    ///     Visits the children of the sql "at time zone" expression.
+    /// </summary>
+    /// <param name="atTimeZoneExpression">The expression to visit.</param>
+    /// <returns>The modified expression, if it or any subexpression was modified; otherwise, returns the original expression.</returns>
+    protected abstract Expression VisitAtTimeZone(AtTimeZoneExpression atTimeZoneExpression);
+
     /// <summary>
     ///     Visits the children of the case expression.
     /// </summary>
@@ -277,7 +288,7 @@ protected override Expression VisitExtension(Expression extensionExpression)
     protected abstract Expression VisitSqlConstant(SqlConstantExpression sqlConstantExpression);
 
     /// <summary>
-    ///     Visits the children of the sql fragent expression.
+    ///     Visits the children of the sql fragment expression.
     /// </summary>
     /// <param name="sqlFragmentExpression">The expression to visit.</param>
     /// <returns>The modified expression, if it or any subexpression was modified; otherwise, returns the original expression.</returns>

src/EFCore.Relational/Query/SqlExpressions/AtTimeZoneExpression.cs

@@ -0,0 +1,91 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions;
+
+/// <summary>
+///     <para>
+///         An expression that represents an AT TIME ZONE operation in a SQL tree.
+///     </para>
+///     <para>
+///         This type is typically used by database providers (and other extensions). It is generally
+///         not used in application code.
+///     </para>
+/// </summary>
+public class AtTimeZoneExpression : SqlExpression
+{
+    /// <summary>
+    ///     Creates a new instance of the <see cref="AtTimeZoneExpression" /> class.
+    /// </summary>
+    /// <param name="operand">The operand on which to perform the time zone conversion.</param>
+    /// <param name="timeZone">The time zone to convert to.</param>
+    /// <param name="type">The <see cref="Type" /> of the expression.</param>
+    /// <param name="typeMapping">The <see cref="RelationalTypeMapping" /> associated with the expression.</param>
+    public AtTimeZoneExpression(
+        SqlExpression operand,
+        SqlExpression timeZone,
+        Type type,
+        RelationalTypeMapping? typeMapping)
+        : base(type, typeMapping)
+    {
+        Operand = operand;
+        TimeZone = timeZone;
+    }
+
+    /// <summary>
+    ///     The input operand on which to apply the time zone.
+    /// </summary>
+    public virtual SqlExpression Operand { get; }
+
+    /// <summary>
+    ///     The time zone to be applied.
+    /// </summary>
+    public virtual SqlExpression TimeZone { get; }
+
+    /// <inheritdoc />
+    protected override Expression VisitChildren(ExpressionVisitor visitor)
+    {
+        var operand = (SqlExpression)visitor.Visit(Operand);
+        var timeZone = (SqlExpression)visitor.Visit(TimeZone);
+
+        return Update(operand, timeZone);
+    }
+
+    /// <summary>
+    ///     Creates a new expression that is like this one, but using the supplied children. If all of the children are the same, it will
+    ///     return this expression.
+    /// </summary>
+    /// <param name="operand">The <see cref="Operand" /> property of the result.</param>
+    /// <param name="timeZone">The <see cref="TimeZone" /> property of the result.</param>
+    /// <returns>This expression if no children changed, or an expression with the updated children.</returns>
+    public virtual AtTimeZoneExpression Update(SqlExpression operand, SqlExpression timeZone)
+        => operand != Operand || timeZone != TimeZone
+            ? new AtTimeZoneExpression(operand, timeZone, Type, TypeMapping)
+            : this;
+
+    /// <inheritdoc />
+    protected override void Print(ExpressionPrinter expressionPrinter)
+    {
+        expressionPrinter.Visit(Operand);
+
+        expressionPrinter.Append(" AT TIME ZONE ");
+
+        expressionPrinter.Visit(TimeZone);
+    }
+
+    /// <inheritdoc />
+    public override bool Equals(object? obj)
+        => obj != null
+            && (ReferenceEquals(this, obj)
+                || obj is AtTimeZoneExpression atTimeZoneExpression
+                && Equals(atTimeZoneExpression));
+
+    private bool Equals(AtTimeZoneExpression atTimeZoneExpression)
+        => base.Equals(atTimeZoneExpression)
+            && Operand.Equals(atTimeZoneExpression.Operand)
+            && TimeZone.Equals(atTimeZoneExpression.TimeZone);
+
+    /// <inheritdoc />
+    public override int GetHashCode()
+        => HashCode.Combine(base.GetHashCode(), Operand, TimeZone);
+}

src/EFCore.Relational/Query/SqlNullabilityProcessor.cs

@@ -357,6 +357,8 @@ protected virtual SelectExpression Visit(SelectExpression selectExpression)
         var nullValueColumnsCount = _nullValueColumns.Count;
         var result = sqlExpression switch
         {
+            AtTimeZoneExpression sqlAtTimeZoneExpression
+                => VisitAtTimeZone(sqlAtTimeZoneExpression, allowOptimizedExpansion, out nullable),
             CaseExpression caseExpression
                 => VisitCase(caseExpression, allowOptimizedExpansion, out nullable),
             CollateExpression collateExpression
@@ -413,6 +415,25 @@ protected virtual SqlExpression VisitCustomSqlExpression(
         => throw new InvalidOperationException(
             RelationalStrings.UnhandledExpressionInVisitor(sqlExpression, sqlExpression.GetType(), nameof(SqlNullabilityProcessor)));
 
+    /// <summary>
+    ///     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.
+    /// </summary>
+    protected virtual SqlExpression VisitAtTimeZone(
+        AtTimeZoneExpression atTimeZoneExpression,
+        bool allowOptimizedExpansion,
+        out bool nullable)
+    {
+        var operand = Visit(atTimeZoneExpression.Operand, out var operandNullable);
+        var timeZone = Visit(atTimeZoneExpression.TimeZone, out var timeZoneNullable);
+
+        nullable = operandNullable || timeZoneNullable;
+
+        return atTimeZoneExpression.Update(operand, timeZone);
+    }
+
     /// <summary>
     ///     Visits a <see cref="CaseExpression" /> and computes its nullability.
     /// </summary>

src/EFCore.SqlServer/Extensions/SqlServerDbFunctionsExtensions.cs

@@ -1438,4 +1438,50 @@ public static bool IsNumeric(
         this DbFunctions _,
         string expression)
         => throw new InvalidOperationException(CoreStrings.FunctionOnClient(nameof(IsNumeric)));
+
+    /// <summary>
+    ///     Converts <paramref name="dateTime" /> to the corresponding <c>datetimeoffset</c> in the target <paramref name="timeZone" />.
+    ///     Corresponds to the SQL Server's <c>AT TIME ZONE</c> construct.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         Note that the <see cref="DateTime.Kind" /> of <paramref name="dateTime" /> is not taken into account when performing the
+    ///         conversion; the offset for the provided time zone is simply applied as-is.
+    ///     </para>
+    ///     <para>
+    ///         See <see href="https://aka.ms/efcore-docs-database-functions">Database functions</see>, and
+    ///         <see href="https://aka.ms/efcore-docs-sqlserver">Accessing SQL Server and SQL Azure databases with EF Core</see>
+    ///         for more information and examples.
+    ///     </para>
+    /// </remarks>
+    /// <param name="_">The <see cref="DbFunctions" /> instance.</param>
+    /// <param name="dateTime">The value to convert to <c>datetimeoffset</c>.</param>
+    /// <param name="timeZone">A valid SQL Server time zone ID.</param>
+    /// <returns>The <c>datetimeoffset</c> resulting from the conversion.</returns>
+    /// <seealso href="https://docs.microsoft.com/sql/t-sql/queries/at-time-zone-transact-sql">SQL Server documentation for <c>AT TIME ZONE</c>.</seealso>
+    public static DateTimeOffset AtTimeZone(
+        this DbFunctions _,
+        DateTime dateTime,
+        string timeZone)
+        => throw new InvalidOperationException(CoreStrings.FunctionOnClient(nameof(AtTimeZone)));
+
+    /// <summary>
+    ///     Converts <paramref name="dateTimeOffset" /> to the time zone specified by <paramref name="timeZone"/>.
+    ///     Corresponds to the SQL Server's <c>AT TIME ZONE</c> construct.
+    /// </summary>
+    /// <remarks>
+    ///     See <see href="https://aka.ms/efcore-docs-database-functions">Database functions</see>, and
+    ///     <see href="https://aka.ms/efcore-docs-sqlserver">Accessing SQL Server and SQL Azure databases with EF Core</see>
+    ///     for more information and examples.
+    /// </remarks>
+    /// <param name="_">The <see cref="DbFunctions" /> instance.</param>
+    /// <param name="dateTimeOffset">The value on which to perform the time zone conversion.</param>
+    /// <param name="timeZone">A valid SQL Server time zone ID.</param>
+    /// <returns>The <c>datetimeoffset</c> resulting from the conversion.</returns>
+    /// <seealso href="https://docs.microsoft.com/sql/t-sql/queries/at-time-zone-transact-sql">SQL Server documentation for <c>AT TIME ZONE</c>.</seealso>
+    public static DateTimeOffset AtTimeZone(
+        this DbFunctions _,
+        DateTimeOffset dateTimeOffset,
+        string timeZone)
+        => throw new InvalidOperationException(CoreStrings.FunctionOnClient(nameof(AtTimeZone)));
 }

src/EFCore.SqlServer/Extensions/SqlServerServiceCollectionExtensions.cs

@@ -123,6 +123,7 @@ public static IServiceCollection AddEntityFrameworkSqlServer(this IServiceCollec
             .TryAdd<IMemberTranslatorProvider, SqlServerMemberTranslatorProvider>()
             .TryAdd<IQuerySqlGeneratorFactory, SqlServerQuerySqlGeneratorFactory>()
             .TryAdd<IRelationalSqlTranslatingExpressionVisitorFactory, SqlServerSqlTranslatingExpressionVisitorFactory>()
+            .TryAdd<ISqlExpressionFactory, SqlServerSqlExpressionFactory>()
             .TryAdd<IRelationalParameterBasedSqlProcessorFactory, SqlServerParameterBasedSqlProcessorFactory>()
             .TryAdd<INavigationExpansionExtensibilityHelper, SqlServerNavigationExpansionExtensibilityHelper>()
             .TryAdd<IQueryableMethodTranslatingExpressionVisitorFactory, SqlServerQueryableMethodTranslatingExpressionVisitorFactory>()

src/EFCore.SqlServer/Query/Internal/SearchConditionConvertingExpressionVisitor.cs

@@ -306,6 +306,23 @@ protected override Expression VisitSelect(SelectExpression selectExpression)
             : selectExpression;
     }
 
+    /// <summary>
+    ///     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.
+    /// </summary>
+    protected override Expression VisitAtTimeZone(AtTimeZoneExpression atTimeZoneExpression)
+    {
+        var parentSearchCondition = _isSearchCondition;
+        _isSearchCondition = false;
+        var operand = (SqlExpression)Visit(atTimeZoneExpression.Operand);
+        var timeZone = (SqlExpression)Visit(atTimeZoneExpression.TimeZone);
+        _isSearchCondition = parentSearchCondition;
+
+        return atTimeZoneExpression.Update(operand, timeZone);
+    }
+
     /// <summary>
     ///     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

src/EFCore.SqlServer/Query/Internal/SqlServerDateTimeMethodTranslator.cs

@@ -31,6 +31,14 @@ public class SqlServerDateTimeMethodTranslator : IMethodCallTranslator
         { typeof(DateTimeOffset).GetRuntimeMethod(nameof(DateTimeOffset.AddMilliseconds), new[] { typeof(double) })!, "millisecond" }
     };
 
+    private static readonly MethodInfo AtTimeZoneDateTimeOffsetMethodInfo = typeof(SqlServerDbFunctionsExtensions)
+        .GetRuntimeMethod(
+            nameof(SqlServerDbFunctionsExtensions.AtTimeZone), new[] { typeof(DbFunctions), typeof(DateTimeOffset), typeof(string) })!;
+
+    private static readonly MethodInfo AtTimeZoneDateTimeMethodInfo = typeof(SqlServerDbFunctionsExtensions)
+        .GetRuntimeMethod(
+            nameof(SqlServerDbFunctionsExtensions.AtTimeZone), new[] { typeof(DbFunctions), typeof(DateTime), typeof(string) })!;
+
     private readonly ISqlExpressionFactory _sqlExpressionFactory;
     private readonly IRelationalTypeMappingSource _typeMappingSource;
 
@@ -89,6 +97,48 @@ public SqlServerDateTimeMethodTranslator(
                 instance.TypeMapping);
         }
 
+        if (method == AtTimeZoneDateTimeOffsetMethodInfo || method == AtTimeZoneDateTimeMethodInfo)
+        {
+            var (operand, timeZone) = (arguments[1], arguments[2]);
+
+            RelationalTypeMapping? resultTypeMapping = null;
+
+            // The AT TIME ZONE construct bubbles up the precision of its operand, so when invoked over datetime2(2) it returns a
+            // datetimeoffset(2). So if the operand has a type mapping, bubble it up accordingly, otherwise allow the result type mapping
+            // to be inferred.
+            if (operand.TypeMapping is { } operandTypeMapping)
+            {
+                switch (operandTypeMapping.StoreTypeNameBase)
+                {
+                    case "datetimeoffset":
+                        resultTypeMapping = operandTypeMapping;
+                        break;
+                    case "datetime" or "datetime2" or "smalldatetime":
+                        resultTypeMapping = _typeMappingSource.FindMapping(
+                            typeof(DateTimeOffset), "datetimeoffset", precision: operandTypeMapping.Precision);
+                        break;
+                    default:
+                        Check.DebugAssert(
+                            false,
+                            $"Unknown operand type mapping '{operandTypeMapping.StoreTypeNameBase}' when translating EF.Functions.AtTimeZone");
+                        break;
+                }
+            }
+
+            if (operand is SqlConstantExpression)
+            {
+                // Our constant representation for datetime/datetimeoffset is an untyped string literal, which the AT TIME ZONE expression
+                // does not accept. Type it explicitly.
+                operand = _sqlExpressionFactory.Convert(operand, operand.Type);
+            }
+
+            return new AtTimeZoneExpression(
+                operand,
+                _sqlExpressionFactory.ApplyTypeMapping(timeZone, _typeMappingSource.FindMapping("varchar")),
+                typeof(DateTimeOffset),
+                resultTypeMapping);
+        }
+
         return null;
     }
 }