Entityframework.docs: Improve documentation on how to write an EF Core provider

[divega]

Currently we have something very brief at https://docs.microsoft.com/ef/core/providers/writing-a-provider pointing to @ajcvickers's blog.

It would be good to update this to cover:

• Support for EF Core 2.1 features
• The mechanics of setting up spec tests
• The mechanics of adding provider specific extension methods

Whether this should be in a blog post or if it needs to be part of the documentation is something we can discuss, but I would be inclined to have it in the actual documentation.

[omatrot]

I'd like to write a scaffolding only provider around edmx files in order to fill the gap for all of us having existing edmx files that we want to keep around in order to create entities and DbContexts.

Any information that could allow me to start would be very much appreciated. May be this would be an interesting contribution to the docs.

[ajcvickers]

Suggestion from @ErikEJ on https://github.com/dotnet/efcore/issues/20793#issuecomment-621943308

It would lower the barrier to have a "template/null" provider to use as a starting point. But of course it can quickly become stale.

[roji]

Ideally this would be built as part of CI, to keep it in at least minimal sync with EF...

[ErikEJ]

@roji do you think there would be any value in this?

[roji]

Yeah, I think it would... Our docs repo has a set of samples - which now even get built in CI - so it could live there. On the other hand, if we put it in the normal repo it would naturally evolve as we change EF Core...

[ErikEJ]

I think it is better to fix it to depend on a released version of EF Core, and then just update on new release (if needed at all)

[smitpatel]

Releases to consider

• LTS release
• Current release (stable)
• Current preview

I think current preview would provide slightly lesser value. If I am writing a provider from scratch, I would want to depend on stable release so I can build my provider and release it. It would be easy after 3.1 to move to next major release for providers even with breaking changes. The issue with targeting previews would be constantly moving target. If EF Core added some API in one preview but changed it in another preview (we love API reviews), then provider has unnecessary effort to keep changing things when writing the core provider at the same time.

[ErikEJ]

@smitpatel exactly my experience/pain during EF 7 previews

[roji]

I think we should be much more stable now than we used to be - but I agree that there's not that much value to a provider template that tracks previews. So maybe just tracking the current stable release is enough (an additional one for LTS seems to be a bit overkill)? If so, then just putting it in our doc repo under samples should be good...

On another note, I assume we're discussing about a relational provider template - or do we think that a non-relational sample is valuable as well?

Are you interested in doing this @ErikEJ?

[ErikEJ]

@roji yes, the relational. I could just base it on something similar to the initial commit I mentioned above. A no-name ANSI SQL provider...

[ajcvickers]

If we put it in the main repo, then it would evolve along with the other providers _and_ there will still always be a branch/tag to get the snapshot of the provider that aligns with a given release.

[ErikEJ]

Good point, but should the initial commit not target 3.1?

[ajcvickers]

Yeah, that would be ideal.

[roji]

@ajcvickers the point made above is that the main value of this is for the latest stable release, since that's what provider writers are likely to target. If that is so, then the template would depend on the latest released version and not on the latest code in master... and we'd evolve it for every release manually, a bit like how we're supposed to do for the doc samples.

[smitpatel]

The repo to host is less important. The sample should use package references rather than project references.

[ErikEJ]

@smitpatel good point - just let me know which repo you prefer 😊

[roji]

If we agree to use package references, I'd vote for putting it in the docs repo. It really is a sample, and has no value being in the main repo.

[ajcvickers]

@ErikEJ We discussed this and we're thinking that we could try this out on https://github.com/efcore first to see what it looks like and how it evolves. We could potentially move it somewhere else later.

[ErikEJ]

Yes, I will discuss details in the newly created repo there...