Are EF Core 3.1 ExecuteSqlRaw / ExecuteSqlRawAsync drop-in replacements for ExecuteSqlCommand / ExecuteSqlCommandAsync?

Question

Upon upgrade to EFCore 3.1 deprecated warnings appeared:

Warning CS0618 'RelationalDatabaseFacadeExtensions.ExecuteSqlCommandAsync(DatabaseFacade, RawSqlString, params object[])' is obsolete: 'For the async execution of SQL queries using plain strings, use ExecuteSqlRawAsync instead. For the async execution of SQL queries using interpolated string syntax to create parameters, use ExecuteSqlInterpolatedAsync instead.'

Warning CS0618 'RelationalDatabaseFacadeExtensions.ExecuteSqlCommand(DatabaseFacade, RawSqlString, params object[])' is obsolete: 'For the execution of SQL queries using plain strings, use ExecuteSqlRaw instead. For the execution of SQL queries using interpolated string syntax to create parameters, use ExecuteSqlInterpolated instead.'

The old code to which they relate looks like:

context.Database.ExecuteSqlCommand("DELETE FROM Table WHERE ID = @p0", id);
await context.Database.ExecuteSqlCommandAsync("DELETE FROM Table2 WHERE ID = @p0", id);

Consulting the fine manual, typical SQL Server parameters @somename aren't discussed at all, and in fact I don't even see how the example code in the docs, where they show opening a parenthesis after a table name, is valid SQL syntax:

context.Database.ExecuteSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)

I didn't see where the docs ever define the contents of the userSuppliedSearchTerm variable or its type, and I'm struggling to see how it could be sensibly a nugget of SQL (string userSuppliedSearchTerm = "WHERE id = 123"; with baked in values? SQL Injection?) or a single primitive value (int userSuppliedSearchTerm = 123) so does it mean it's some kind of custom type that specifies the db column name and the value ? How does EFCore know which column from the table is to be queried? Does EFCore sort out the syntax error presented by the parentheses? Are the parentheses mandatory for EFCore to understand the query?

Ultimately my question is: given that my ExecuteSqlCommand code made sense, and the docs for ExecuteSqlRaw make little sense/seem poorly explained, how do we go from this working code:

var id = 123;
context.Database.ExecuteSqlCommand("DELETE FROM Table WHERE ID = @p0", id);

To using ExecuteSqlRaw?

SomeType x = ???;
context.Database.ExecuteSqlRaw("???", x);

Answer 1

The rule is simple.

EF Core 2.x has 3 ExecuteSqlCommand overloads:

public static int ExecuteSqlCommand(this DatabaseFacade databaseFacade,
    RawSqlString sql, params object[] parameters); // 1
public static int ExecuteSqlCommand(this DatabaseFacade databaseFacade,
   RawSqlString sql, IEnumerable<object> parameters); // 2
public static int ExecuteSqlCommand(this DatabaseFacade databaseFacade,
    FormattableString sql); // 3

which in EF Core 3.x are mapped to

public static int ExecuteSqlRaw(this DatabaseFacade databaseFacade,
    string sql, params object[] parameters); // 1
public static int ExecuteSqlRaw(this DatabaseFacade databaseFacade,
    string sql, IEnumerable<object> parameters); // 2
public static int ExecuteSqlInterpolated(this DatabaseFacade databaseFacade,
    FormattableString sql); // 3

Functionally they are fully equivalent. Raw overloads supports the same placeholders and parameter values (both named and unnamed) as v2.x overloads #1 and #2. And Interpolated has the exact same behavior as the v2.x overload #3.

The reason for renaming the method and using different names for interpolated and non interpolated sql parameter is the C# compile time overload resolution for v2.x overloads #1 and #3. Sometimes it chooses interpolated when the intent was to use the other one, and vise versa. Having separate names makes intent clear.

You can read more about the reasoning in EF Core 3.0 Breaking Changes - FromSql, ExecuteSql, and ExecuteSqlAsync have been renamed.

The information about supported parameter placeholders,names and values can be found in Raw SQL queries - Passing parameters.

But to answer your concrete question, if the existing v2.x code is

context.Database.ExecuteSqlCommand("DELETE FROM Table WHERE ID = @p0", id);

then change it to ExecuteSqlRaw.

And if was

context.Database.ExecuteSqlCommand($"DELETE FROM Table WHERE ID = {id}");

then change it to ExecuteSqlInterpolated.