Document advanced user-defined function mapping

[Copilot]

The user-defined function mapping guide omitted several registration, type-mapping, nullability, and translation APIs. It also lacked a practical built-in JSON function example.

• Function registration

  • Document lambda-based HasDbFunction registration and default arguments.
  • Cover DbFunctionAttribute, schemas, built-in functions, and nullability metadata.

• Store-type and JSON mapping

  • Demonstrate mapping converted CLR types to function parameter store types.
  • Add a SQL Server JSON_VALUE example and clarify value-converter limitations.

[DbFunction(Name = "JSON_VALUE", IsBuiltIn = true, IsNullable = true)]
public static string JsonValue(Dictionary<string, string> json, string path)
    => throw new NotSupportedException();

var function = modelBuilder.HasDbFunction(() => JsonValue(default, default));
function.HasStoreType("nvarchar(4000)");
function.HasParameter("json").HasStoreType("nvarchar(max)");

• Translation behavior
  • Explain PropagatesNullability and link it to query null semantics.
  • Add cautions for constructing HasTranslation SQL expression trees.
  • Clarify that table-valued functions cannot use HasTranslation.

• Fixes Add missing content to user defined function mapping #2925

[Copilot]

Pull request overview

Expands advanced EF Core user-defined function mapping documentation and samples.

Changes:

• Adds lambda registration, schema, nullability, and translation guidance.
• Demonstrates SQL Server JSON_VALUE with converted CLR types.
• Clarifies HasTranslation limitations and nullability propagation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
Program.cs	Adds the JSON function query.
Model.cs	Adds JSON entity, conversion, and function mapping.
user-defined-function-mapping.md	Documents advanced mapping APIs and behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

entity-framework/core/querying/user-defined-function-mapping.md:81

• JsonEntity is required by the new example, but its declaration (and the JsonEntities context property) is outside every referenced snippet, so readers cannot reproduce the configuration shown below from the page. Add a dedicated entity/context snippet before this paragraph, or include these declarations in an existing referenced region.

In this example, `JsonEntity.Metadata` is a dictionary stored as `nvarchar(max)` through a value converter. The `json` function parameter has the same store type, while the result uses the `nvarchar(4000)` type returned by `JSON_VALUE`:

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

entity-framework/core/querying/user-defined-function-mapping.md:122

• The translation sample immediately above violates this new requirement: ABS receives one SQL argument, but Model.cs:200 supplies two argumentsPropagateNullability entries. EF Core 10 requires these counts to match and throws InvalidOperationException when PercentageDifference is translated, so running the documented sample fails. Update that list to [true] while adding this caution.

> [!CAUTION]
> `HasTranslation` works with the SQL expression tree, not SQL text. The translation must construct valid <xref:Microsoft.EntityFrameworkCore.Query.SqlExpressions.SqlExpression> objects with the correct type mappings, nullability, and argument nullability propagation. Incorrect metadata can produce invalid SQL or incorrect query results, and the expression types used by a translation may be specific to a database provider. Use this low-level API only after understanding the provider's SQL expression tree; prefer a regular function mapping or an existing provider translation when possible.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

entity-framework/core/querying/user-defined-function-mapping.md:122

• The referenced HasTranslation sample does not satisfy this new requirement: its ABS expression has one SQL argument but passes argumentsPropagateNullability: [true, true]. SqlFunctionExpression requires these counts to match, so executing query2 throws InconsistentNumberOfArguments instead of producing the SQL shown. Update that sample metadata to [true].

> `HasTranslation` works with the SQL expression tree, not SQL text. The translation must construct valid <xref:Microsoft.EntityFrameworkCore.Query.SqlExpressions.SqlExpression> objects with the correct type mappings, nullability, and argument nullability propagation. Incorrect metadata can produce invalid SQL or incorrect query results, and the expression types used by a translation may be specific to a database provider. Use this low-level API only after understanding the provider's SQL expression tree; prefer a regular function mapping or an existing provider translation when possible.