search

dotnet / EntityFramework.Docs

Documentation for Entity Framework Core and Entity Framework 6
https://docs.microsoft.com/ef/
Creative Commons Attribution 4.0 International
1.62k stars 1.96k forks source link

Be explicit about value types not being a good match to entity types #3604

Open yecril71pl opened 2 years ago

yecril71pl commented 2 years ago

A property is considered a navigation property if the type it points to ~can not~ cannot be mapped as a scalar type by the current database provider and …

What does it mean that a property points to a type? The straightforward interpretation, that the value of a property is a Type, is obviously wrong.

Did you mean its type … is enumerable and the enumerated values cannot be mapped? Because this is what it seems to be. But even if this is the case, the reader does not know yet what cannot be mapped means; the previous chapters do not mention that only a few types can be mapped :thinking:

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

roji commented 2 years ago

@yecril71pl navigations aren't necessarily enumerable - reference navigations represent one-to-one relationships. If the property CLR type is supported by the database provider as a native sclar type, the property is mapped as a column; whereas if the type is a known, mapped entity type in the model, EF treats it as a reference navigation by default.

The phrase "cannot be mapped as a scalar type by the current database provider" seems pretty straightforward to me; it may be slightly clearer to simply say "isn't supported" instead of "cannot be mapped", but I don't think it's very significant here.

yecril71pl commented 2 years ago

The phrase "cannot be mapped as a scalar type by the current database provider" seems pretty straightforward to me; it may be slightly clearer to simply say "isn't supported" instead of "cannot be mapped", but I don't think it's very significant here.

Of course it looks obvious to you; however, it is all Greek to a person who reads it for the first time, I am afraid. Also, what I was missing in the text is that entity types cannot be scalar (in particular, an entity cannot be a value type, which is quite unexpected because an entity type feels like a value type for all practical purposes, especially when it contains no foreign keys). I tried to find this information in the preceding chapters and I was unable to.

roji commented 2 years ago

Our getting started page discusses entity classes multiple types and shows examples of class definitions for them. We may not explicitly say that entity types cannot be scalar, but there's a whole lot of introductory docs on modeling with examples of entity classes. The docs you're commenting on - relationships - isn't the first page users that new users are expected to read on their very first encounter with EF Core; it's reasonable to assume that some basic concepts have been acquired, otherwise we'd have to repeat all concepts and definitions in every single doc page.

Can you explain what your confusion/expectation here was? Were you expecting a navigation to be set up to a scalar type? What would that even mean in a relational database etc.?

ajcvickers commented 2 years ago

Potentially helped by #1665.

yecril71pl commented 2 years ago

Our getting started page discusses entity classes multiple types and shows examples of class definitions for them. We may not explicitly say that entity types cannot be scalar, but there's a whole lot of introductory docs on modelling with examples of entity classes.

Yes, and those examples do not show that value types can be entities but that the text around does not say that they cannot be.

Can you explain what your confusion/expectation here was? Were you expecting a navigation to be set up to a scalar type? What would that even mean in a relational database etc.?

Ugh, not exactly a scalar type like int, rather a value type like a location. A location is not a scalar, it is a vector, but such a vector can be and would be represented as a value type in pure C# code.

I understand that value types like Uri (which is not a value type, but could as well be) can be treated both as entities and as scalars. My scenario is: I would like to make a Uri a separate entity even if it hypothetically were declared as a value type. And the text should say how or why not.

roji commented 2 years ago

Maybe we could add a note in https://docs.microsoft.com/en-us/ef/core/modeling/entity-types on why value entity types are a bad idea (they cannot be tracked for changes).