Document EF Core architecture and internal technical details

[ajcvickers]

To make it easier for contributors and provider authors to understand the code.

Please comment on this issue with internal areas you would like to see documented.

Working list of possible topics to document. This list will evolve in the issue as we make progress. Not everything in the list will necessarily make it to documentation--it will depend on value, resources, etc. as usual.

• Internal service provider
• Singleton options
• Dependency objects
• DbContext initialization
• Context pooling
• Change tracking
• SaveChanges/update pipeline
• Everything query!
• Proxies
• Lazy-loading
• Constructor injection
• Everything model building! (Document high-level model building concepts #779)
• Model building conventions (Document conventions API #1937)
• Shadow properties
• Logging
• Interceptors
• Diagnostics
• External model building
• Metadata interfaces (mutable, etc.)
• Weak entity types
• Owned entity types
• Relational mapping (Create a consistent relational model API efcore#12846)
• Pubternal types
• Parameter generation and facets

[ajcvickers]

@aspnet/efteam Please add anything with internals that it might be worth documenting. I would rather have too many things on this list and then trim it, so treat this as brainstorming list--no bad ideas!

[bricelam]

• Plugins (type mapping, translators, etc.)
• Migrations
  • Diffing (especially how provider model attributes become migration operation attributes)
  • DDL generation
• Scaffolding/Reverse Engineering
  • How design-time services are discovered
  • Reading database metadata
  • Provider code hooks (UseMyProvider, literals, etc.)
• How the tools work (dotnet-ef and the PMC cmdlets)

[HamedFathi]

Please consider these:

1. How to get current Table/Column/... information from DbContext. Like this

2. How to call the scaffold/reverse tool by code (Not CLI). Like this

[ssg]

I'm not sure if this counts as "internals" but after EF Core 3.0, satisfying the query compiler to run the code on the server-side has been really time consuming. I don't argue the benefits of the change but it's not a straightforward process. I wish there was a documentation comparing client-side running queries with equivalent server-side running ones.

[tudort-iquest]

It would be great to see how the major patterns were implemented (or not) in EF - identity map, data mapper, repository, unit-of-work, lazy loading, association table mapping, metadata mapping, query object etc..

[kant2002]

I in general agree with @ssg , but I want to see how do you generate SQL from different kind of queries. All releases of EF Core starting from betas has changes which require rewriting of the queries to satisfy new version. Expecially many issues I see withing queries which involve GROUP BY or other aggregate functions. If you explain how do you generate SQL using your internal model, it would be easier to write LINQ which will conform to your expected set of queries.

[kant2002]

Also what is TPT, TPH, TPC and PMC ? It is not very clear.

[tudort-iquest]

Also what is TPT, TPH, TPC and PMC ? It is not very clear.

table per type, table per hierarchy, table per concrete class - most O/RMs support these inheritance mapping strategies, maybe under different names..

[kant2002]

Thanks, I get it. I decipher TPT and PMC myself, but other abbreviations not very often I see in MS documentation (or maybe communication better to say). So that's why I ask. Maybe I'm not alone in that.

[explorer14]

• change tracking
• interceptors
• save changes
• context pooling
  , Please!

[bricelam]

We've had a few community standups related to this:

• How to Add a Feature to EF Core
• Internal Dependency Injection
• DbContext Configuration and Lifetime
• IQueryable, LINQ and the EF Core query pipeline
• Model Building

[roji]

Awesome - let's add these to the provider writer "docs": #4424.