Add AtTimeZoneExpression and some relevant translations

Closes dotnet#26199
Closes dotnet#26971

All.sln.DotSettings

@@ -284,6 +284,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

@@ -17,7 +17,6 @@ namespace Microsoft.EntityFrameworkCore.Query;
 /// </summary>
 public class QuerySqlGenerator : SqlExpressionVisitor
 {
-
     private static readonly Dictionary<ExpressionType, string> _operatorMap = new()
     {
         { ExpressionType.Equal, " = " },
@@ -820,6 +819,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>
@@ -839,7 +874,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/SqlExpressionVisitor.cs

@@ -25,6 +25,9 @@ protected override Expression VisitExtension(Expression extensionExpression)
                 return shapedQueryExpression.Update(
                     Visit(shapedQueryExpression.QueryExpression), shapedQueryExpression.ShaperExpression);
 
+            case AtTimeZoneExpression atTimeZoneExpression:
+                return VisitAtTimeZone(atTimeZoneExpression);
+
             case CaseExpression caseExpression:
                 return VisitCase(caseExpression);
 
@@ -116,6 +119,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>
@@ -278,7 +289,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 left operand.
+    /// </summary>
+    public virtual SqlExpression Operand { get; }
+
+    /// <summary>
+    ///     The right operand.
+    /// </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

@@ -348,6 +348,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
@@ -404,6 +406,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,22 @@ 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"/>.
+    /// </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="dateTime">The value to convert to <c>datetimeoffset</c>.</param>
+    /// <param name="timeZone">The time zone to convert to.</param>
+    /// <returns>The <c>datetimeoffset</c> resulting from the conversion.</returns>
+    public static DateTimeOffset AtTimeZone(
+        this DbFunctions _,
+        DateTime dateTime,
+        string timeZone)
+        => throw new InvalidOperationException(CoreStrings.FunctionOnClient(nameof(AtTimeZone)));
 }

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,12 @@ public class SqlServerDateTimeMethodTranslator : IMethodCallTranslator
         { typeof(DateTimeOffset).GetRequiredRuntimeMethod(nameof(DateTimeOffset.AddMilliseconds), typeof(double)), "millisecond" }
     };
 
+    private static readonly MethodInfo _atTimeZoneMethodInfo = typeof(SqlServerDbFunctionsExtensions)
+        .GetRequiredRuntimeMethod(nameof(SqlServerDbFunctionsExtensions.AtTimeZone), typeof(DbFunctions), typeof(DateTime), typeof(string));
+
+    private static readonly MethodInfo _convertTimeBySystemTimeZoneIdMethodInfo = typeof(TimeZoneInfo)
+        .GetRequiredRuntimeMethod(nameof(TimeZoneInfo.ConvertTimeBySystemTimeZoneId), typeof(DateTimeOffset), typeof(string));
+
     private readonly ISqlExpressionFactory _sqlExpressionFactory;
     private readonly IRelationalTypeMappingSource _typeMappingSource;
 
@@ -89,6 +95,42 @@ public SqlServerDateTimeMethodTranslator(
                 instance.TypeMapping);
         }
 
+        if (method == _convertTimeBySystemTimeZoneIdMethodInfo)
+        {
+            var (operand, timeZone) = (arguments[0], arguments[1]);
+
+            if (operand is SqlConstantExpression)
+            {
+                // Our constant representation for datetimeoffset is an untyped string literal, which the AT TIME ZONE expression does not
+                // accept. Type it explicitly.
+                operand = _sqlExpressionFactory.Convert(
+                    operand, typeof(DateTimeOffset), _typeMappingSource.FindMapping(typeof(DateTimeOffset)));
+            }
+
+            operand = _sqlExpressionFactory.ApplyDefaultTypeMapping(operand);
+            timeZone = _sqlExpressionFactory.ApplyDefaultTypeMapping(timeZone);
+
+            return new AtTimeZoneExpression(operand, timeZone, typeof(DateTimeOffset), operand.TypeMapping);
+        }
+
+        if (method == _atTimeZoneMethodInfo)
+        {
+            var (operand, timeZone) = (arguments[1], arguments[2]);
+
+            if (operand is SqlConstantExpression)
+            {
+                // Our constant representation for datetime is an untyped string literal, which the AT TIME ZONE expression does not accept.
+                // Type it explicitly.
+                operand = _sqlExpressionFactory.Convert(operand, typeof(DateTime), _typeMappingSource.FindMapping(typeof(DateTime)));
+            }
+
+            return new AtTimeZoneExpression(
+                _sqlExpressionFactory.ApplyDefaultTypeMapping(operand),
+                _sqlExpressionFactory.ApplyDefaultTypeMapping(timeZone),
+                typeof(DateTimeOffset),
+                _typeMappingSource.FindMapping(typeof(DateTimeOffset)));
+        }
+
         return null;
     }
 }

test/EFCore.Specification.Tests/Query/GearsOfWarQueryTestBase.cs

@@ -8269,6 +8269,15 @@ public virtual Task Enum_matching_take_value_gets_different_type_mapping(bool as
                     .Select(g => g.Rank & value));
     }
 
+    [ConditionalTheory]
+    [MemberData(nameof(IsAsyncData))]
+    public virtual Task Where_TimeZoneInfo_ConvertTimeBySystemTimeZoneId_DateTimeOffset(bool async)
+        => AssertQuery(
+            async,
+            ss => ss.Set<Mission>().Where(
+                m => TimeZoneInfo.ConvertTimeBySystemTimeZoneId(m.Timeline, "UTC")
+                    == new DateTimeOffset(2, 3, 1, 13, 0, 0, TimeSpan.Zero)));
+
     protected GearsOfWarContext CreateContext()
         => Fixture.CreateContext();