search

enkodellc / blazorboilerplate

Blazor Boilerplate / Starter Template with MudBlazor
MIT License
1.87k stars 368 forks source link

Entity Framework Wiki Update #358

Closed juicebyjustin closed 3 years ago

juicebyjustin commented 4 years ago

After cloning the solution and working through adding a new object linked to the database I thought the EF wiki could be updated. The changes are below. I replaced most of the bold with inline code marks.

If you approve this format I have a new page I will submit: How to Create a New Object.

Entity Framework

Entity Framework (EF) Core is a lightweight, extensible, open source and cross-platform version of the popular Entity Framework data access technology. EF is used for database calls in Blazor Boilerplate.

Documentation can be found here.

Setup

  1. Install/Update Entity Framework Core CLI
    • Install: dotnet tool install --global dotnet-ef
    • Update: dotnet tool update --global dotnet-ef

Source: https://docs.microsoft.com/en-us/ef/core/miscellaneous/cli/dotnet

DB Contexts

  1. ApplicationDbContext - main db context where all your objects are placed.
  2. PersistedGrantDbContext - used for Identity Server 4.
  3. ConfigurationDbContext - used for Identity Server 4.

Identity Server 4

There are 2 contexts required for Identity Server 4 (IS4). If new versions of IS4 change the db contexts migrations must be added.

Using EntityFramework Core for configuration and operational data

How to Run Migration for IS4 Update

Will be expanded in the future.

Database Schema Changes and Using EF Migrations

Migrations

Keep in mind that every DbContext has its own migrations.

The migrations in BlazorBoilerplate are stored in the BlazorBoilerplate.Storage project. You have to open your shell in this path. Then you have to specify the project where the db contexts are added to the services, because dotnet ef has to know how to find and instantiate them. In our case the so called startup project is BlazorBoilerplate.Server.

The commands are:

ApplicationDbContext: dotnet ef --startup-project ../BlazorBoilerplate.Server/ migrations add 4Preview3 -c ApplicationDbContext --verbose --no-build --configuration Debug_CSB

PersistedGrantDbContext: dotnet ef --startup-project ../BlazorBoilerplate.Server/ migrations add 4Preview3 -c PersistedGrantDbContext --verbose --no-build --configuration Debug_CSB

ConfigurationDbContext: dotnet ef --startup-project ../BlazorBoilerplate.Server/ migrations add 4Preview3 -c ConfigurationDbContext --verbose --no-build --configuration Debug_CSB

Without the --no-build parameter dotnet rebuilds the startup project, but if you have just built it with Visual Studio it is just a waste of time. Also the dotnet build is not the Visual Studio build, so to avoid issue use --no-build.

The name of migration, in this case 4Preview3, is only descriptive and it does not need to be unique, because automatically the name is prepended with date time.

If the command is successful, [datetime]_[migration-name].cs is added to the solution. Also the [db-context-name]ModelSnapshot.cs is updated to reflect the db changes in case a new db has to created.

Create a Migration

  1. Open the package manager console.
  2. cd to Server/BlazorBoilerplate.Storage.
  3. Set the startup project to BlazorBoilerplace.Server
  4. Run the command listed above pending on which context you are using and give a custom migration name.
  5. Find the migration file in BlazorBoilerplate.Storage.Migrations.

Updating the Database

When you run the project, the migrations are applied to the database. The db table __EFMigrationsHistory keeps track of applied migrations without information about the related db context.

To get this information use the following command; for example for ConfigurationDbContext:

dotnet ef --startup-project ../BlazorBoilerplate.Server/ migrations list -c ConfigurationDbContext --verbose --no-build --configuration Debug_SSB

You can also update the database without running the project with the following command (the migration name 4Preview3 is not required):

dotnet ef --startup-project ../BlazorBoilerplate.Server/ database update 4Preview3 -c ConfigurationDbContext --verbose --no-build --configuration Debug_SSB

If you specify a previous migration, you can revert the db changes to that migration.

Warning

The migrations are not smart, when you have an existing db with populated tables. If migrations add keys and/or unique indexes or something else violating referential integrity, you have to manually modify [datetime]_[migration-name].cs for example to add some SQL to fix the errors.

E.g. migrationBuilder.Sql("UPDATE AspNetUserLogins SET Id=NEWID() WHERE Id=''"); to add unique values to a new field before setting as a new primary key.

Troubleshooting

GioviQ commented 4 years ago

Some github projects use https://readthedocs.org/. @juicebyjustin Do you know? Or do you know something similar to make easy pull requests to docs?

juicebyjustin commented 4 years ago

I have not used either @GioviQ. However, this morning I played around and created both a Github page and a Read the Docs project. Both are quick to create the documentation from the repo and auto update on new commits. From testing I believe that Read the Docs is the best option due to the nav bar on the side auto populating when new files are added to the docs.

My Read the Docs site is not perfect due to me playing around. Automapper Read the Docs is a good resource of how a Markdown RTD site could look.

GioviQ commented 4 years ago

@juicebyjustin Good, but at the moment as a collaborator of this repository I have no permissions to perform ReadTheDocs integration (see https://docs.readthedocs.io/en/stable/connected-accounts.html)

juicebyjustin commented 4 years ago

@GioviQ it looks like we need @enkodellc to decide what he wants to do for documentation as he owns this project.

I took this 1 step further today so we could see what Read the Docs would look like with this repos wiki. I forked this project, included the markdown from this wiki in my fork, and published a new branch. My new branch is active on Read the Docs with a custom name. This way we can see what the current wiki would look like in RTD.

This will allow any contributor to modify the wiki with a pull request. @enkodellc if this is the direction you want to go I can create a new issue and make a pull request.

Read the Docs Test with Data from this Repo's Wiki

enkodellc commented 4 years ago

I will review later today. Been a busy lately and did some MatBlazor updates earlier this week. My next free time will be dedicated to BB. Thanks guys for voicing your opinions and your hard work!

GioviQ commented 4 years ago

I am reading https://read.finnsweb.io/exploring-read-the-docs/#markdown-vs-rest-comparison regarding Sphinx vs MxDocs

juicebyjustin commented 4 years ago

The thing that stands out in that read is that Markdown is simple. Sphinx does have the ability to do multiple translations but that requires document writers to write in their language. Whatever is chosen, developers can always write in Markdown and use a converter to get an reST file.

enkodellc commented 4 years ago

First off I quickly looked through this and watched a couple of vids on RtD and Sphinx

I would like to keep it simple & Markdown is simple as @juicebyjustin mentioned. There are a lot of foreign users that use BB so translations isn't a terrible idea but you won't see me doing anything but English.

I do like having to install python to run Sphinx. I am all for any solution that we can host static files on the repo or my server for the docs. Not a deal breaker though.

From my own quick poking it looks like this tutorial will work?? https://tutos.readthedocs.io/en/latest/source/git_rtd.html

If you both agree this a good path then I @GioviQ if you want to implement on master then give it a shot. I need to spend time on BB soon... I am still working hard on my house doing tile so it is quite hard work. I need to focus on that for my marriage :) If I am not too beat up tonight I will be back at my computer.

GioviQ commented 4 years ago

@enkodellc I have no problem to setup readthedocs, but registering to ReadTheDocs and to test all the flow, I should have rights to setup webhooks. Maybe you should consider the option to create a GitHub Organizations named e.g. BlazorBoilerplate moved the current repository there and give me access to those settings.

GioviQ commented 3 years ago

Wiki is superseded by https://blazor-boilerplate.readthedocs.io/en/latest/

Contributors must PR files in https://github.com/enkodellc/blazorboilerplate/tree/master/docs