EntityFramework.Docs
EntityFramework.Docs copied to clipboard
dotnet
Improve documentation on how to write an EF Core provider
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 (e.g. https://github.com/dotnet/efcore/issues/27107#issuecomment-1004923695)
- 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.
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.
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.
Ideally this would be built as part of CI, to keep it in at least minimal sync with EF...
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...
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)
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.
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?
@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...
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.
@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.
The repo to host is less important. The sample should use package references rather than project references.
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.
@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.
Are there any plans to have the docs updated for EFCore5?
The blog it points to is for EFCore1.1! Is the doc still valid? I cannot find DatabaseProviderServices?
I searched in the linked example providers such as SQL Server, npsql, etc but could not find DatabaseProviderServices or RelationalDatabaseProviderServices anywhere in them...
Any ideas? I really need to write a provider but haven't a clue how to or where to start?
Any help would be really appreciated.
Many thanks, David.
@dellams we're indeed lacking good documentation on how to write a provider... Assuming you're looking to develop a provider for a relational database, it's recommended you start with the Npgsql or Pomelo MySQL providers, as these are external projects that aren't part of the EF Core repo. Where relevant, the other providers (Sqlite, SQL Server) can also be consulted.
Start by looking at the different services implemented by these providers, and getting familiar with the general architecture of EF Core. We can then help out with any specific questions.
Yes, thank you, I have already checked them out and was surprised with just how much work and how complex it was to write a provider. I was hoping you could provide a simple bare bones template with the minimum needed to implement a provider?
Do you know when some up to date documentation will be created for this?
What I am trying to do is something a bit more special than just a relational provider, I am attempting to integrate EFCore into the OASIS API I have been building, which integrates all blockchains, holochain, cloud, db's, networks, platforms, APIs, etc. It is like a network of networks, an abstraction layer over the entire internet.
I would love to get some support with this very valuable project, I feel once people understood what I am building a LOT would come and help me build it! :)
https://github.com/NextGenSoftwareUK/Our-World-OASIS-API-HoloNET-HoloUnity-And-.NET-HDK
It would be super cool and powerful to have this abstraction API using EFCore making it super easy to bridge everything to everything through one simple ORM (I love EF and have worked with it many years being a big fan of .NET since its initial release many years ago just after I graduated from University in 2002.) :)
I have worked as a IT consultant/contractor in London building commercial .NET applications of all sizes in all markets, etc so have experience of most of the amazing .NET stack since I have grown as a developer along with .NET... you could say we grew up together! ;-)
BIG FAN! :) Keep up the great work, so happy it is Open Source now and cross platform,... very excited and passionate to help grow the .NET ecosystem with you guys...
I hope to get on the .NET Foundation soon... is that something you guys could help with? When you all understand the wonders I plan to do for the .NET community I think you would want to help me help you... ;-)
Many thanks, David.
@dellams you may find the series of commits in the develop branch here useful: https://github.com/GibraltarSoftware/VistaDB.EFCore
One of the providers that is stalled out is FileContextCore. The fact that there are so many breaking changes between major versions means that ongoing maintenance of providers is very labor intensive especially when there is no documentation.
I have a need to create many EF Core providers and decided to create a template repo for this purpose. It is still a work in progress (i.e. need to get passing unit tests going), but am wondering if this repo would be something that the community would be interested in? And also if it might go a ways toward solving this open issue?
The readme describes the concept of this sample provider.
@DaveRMaltby I do think we skeleton/template provider is a good thing to have, as a starting point for people writing providers.
Some specific points come to mind when looking at your repo; in particular, many services are being overridden that would only be needed in relatively advanced scenarios (e.g. SqlExpressionFactory only for custom SQL expressions, QueryTranslationPostprocessorFactory only for certain advanced scenarios, etc.). I'd advise going with a more minimum approach, implementing only services which a typical provider would have to override, rather than everything.
@DaveRMaltby I do think we skeleton/template provider is a good thing to have, as a starting point for people writing providers.
Some specific points come to mind when looking at your repo; in particular, many services are being overridden that would only be needed in relatively advanced scenarios (e.g. SqlExpressionFactory only for custom SQL expressions, QueryTranslationPostprocessorFactory only for certain advanced scenarios, etc.). I'd advise going with a more minimum approach, implementing only services which a typical provider would have to override, rather than everything.
@roji, thank you for the feedback. Yes, your advice points to the issue that I'm struggling with and I'm sure others who have no idea about the nature of the services offered here. I just used the Npgsql, Pomelo MySQL and SQLite providers as a basis to copy from for this template repo without understanding their purposes. I was trying to get at least one of the tests in EFCore.Relational.Specification.Tests to pass. So far, I have been unsucessful in that endevour and it has been overwhelming as just simply adding the EFCore.SampleProvider.FunctionalTests.Query tests amounts to 443 tests.
Anyhow, I believe now that I need to take a completely different approach. I've now stepped back and am going to take one of the many EF Core providers that I plan to write and create a few unit tests based off of the examples in Getting Started with EF Core. Getting those CRUD tests to pass will give me the understanding and basis for the bare minimum services that are needed. Later, I will add more advanced features to this provider as needed (eventually, adding the migrations/scaffolding that I also need). Ultimately, I'll try to circle around and update the SampleProvider to provide a skeleton/template for others to make use. (And also I hope to provide descriptions about the services as well)
Can you possibly provide a quick list of services that you know are required just to achieve the first step mentioned above of getting simple CRUD unit tests to pass? Thank you.