EFMigrationsManagerUI: Installation and Configuration

By Narendra Bhogavalli

In the previous article, “Using an User Interface to Manage Entity Framework Migrations,” we discussed the user interface to manage Entity Framework migrations and its advantages. In this article, we will talk about how to install and integrate the EFMigrationsManagerUI NuGet package with the ASP.NET MVC applications, along with the sample Web applications.

Install EFMigrationsManagerUI

Step 1

In Visual Studio, open the target MVC project to enable managing the migrations user interface.

  • Right-click the MVC project references and choose Manage NuGet Packages.
  • Search and add the EFMigrationsManagerUI NuGet package.

    Searching for and adding the EFMigrationsManagerUI NuGet package
    Figure 1: Searching for and adding the EFMigrationsManagerUI NuGet package

    This NuGet package has dependencies with the following packages:

    • EntityFramework (>= 6.1.0)
    • WebActivatorEx (>= 2.2.0)
    • Microsoft.AspNet.Mvc (>= 5.2.3)

Step 2

The EFMigrationsManagerUI NuGet package will add the following files in the target project:

  • EFMigrationsManager assembly reference and dependent assemblies if not available
  • EFMigrationsManagerController.cs file under the controller’s folder
  • Adds a EFMigrationsManager folder with the following cshtml files under the Views folder:
    • Publish
    • DbMaintenance

      The EFMigrationsManager folder

      Figure 2: The EFMigrationsManager folder

  • The EFMigrationsManagerConfig.cs file under the App_Start folder.

    The App_Start folder
    Figure 3: The App_Start folder

Step 3

Add the following AppSetting entry in the web.config file.

<add key="EFMigrationsManagerUI:AuthorizedUsers" value=
   "Comma separated admin user names to deploy EF migrations" />

Configuration

Step 1

Install the “EFMigrationsManagerUI” NuGet package.

Step 2

Open the “EFMigrationsManagerConfig” class under the App_Start folder.

Uncomment the following line and pass the Entity Framework Configuration instance as a parameter.

// EFMigrationsManagerSettings.SetEFConfiguration
//    (new EFConfiguration());

Follow these steps to find the EFConfiguration class in the solution:

  1. Search for Class in the solution (usually in models or data projects) that inherits from the class.
  2. Replace EFConfiguration with the class found in the preceding step.

Step 3

Open the web.config file and navigate to the AppSetting section. Update the user names for the following AppSetting.

<add key="EFMigrationsManager:AuthorizedUsers" value=
   "Comma separated admin user names to deploy EF migrations" />
Note:

  1. For multiple admins, enter comma-separated identity names.
  2. For Windows authentication, enter the name as domain\username.
  3. For Forms authentication, enter the name as username@domain.com or firstname.lastname@domain.com, based on the identity name.

Now, you’re all set and ready to manage the Entity Framework migrations through the simple user interface. Run the MVC application and navigate to the following pages:

  • Database deployment: EFMigrationsManager/Publish
  • Rollback database: EFMigrationsManager/Publish?isRollback=True

Additional Configuration

In this section, we will talk about some additional, optional configuration settings.

Step 1: Admin Connection String or EFMigrationsManagerUI-Specific Connection String

It’s recommended that you use a different connection string for EFMigrationsManagerUI. In most cases, Entity Framework migrations (to update a database) need permission for schema changes (create/alter/drop permissions).

On the other hand, an application connection string doesn’t need the admin permissions; also, it’s not recommended. Follow the upcoming steps to provide a different connection string to deploy a database other than the connection string from the Entity Framework configuration.

  • Create another connection string, as shown in Figure 4.

    A new connection string
    Figure 4: A new connection string

  • Open the “EFMigrationsManagerConfig” class under the the App_Start folder and navigate to the Registermethod. Call the EFMigrationsManagerSettings.SetConnectionString method with the admin connection string name. Please check Figure 5 for a quick reference.

    Setting the connection string
    Figure 5: Setting the connection string

Now, the application page will use the connection string with read/write permissions based on the application requirement and EFMigrationManagerUI (database deployment pages) will use an admin connection string with admin permissions to deploy the database.

Step 2: Disable AutoDetect Pending Migrations—Controller/Action Level

If any specific application page is not required to check whether EF migrations are up to date or not, use the attribute shown in Figure 6 at the controller/action level.

Controller/action level attributes
Figure 6: Controller/action level attributes

Example: There’s no need to check the EF Pending migrations for error pages. If the application is throwing some database exception, the application will redirect to the default application error page. Again, if error pages are hitting the database, the application will throw a cascading error in the error pages. To avoid these cases, skip the verification check by using the previous attributes.

Step 3: Disable AutoDetect Pending Migrations—Application Level

By default, when installing the NuGet package, the AutoDetect feature is enabled. To disable this feature, remove the line shown in Figure 7 from the EFMigrationsManagerConfig class and access the database deployment pages with a URL or navigation links.

Disabling the AutoDetect feature
Figure 7: Disabling the AutoDetect feature

Step 4: Alternative Approach to AutoDetect Pending Migrations

The default configuration is with an MVC action filter. An MVC action filter will check pending migrations for each MVC page request. Follow these steps to avoid checking that the migrations are up to date or not on every page request.

Call the highlighted method in Application_Error (see Figure 8). This method will check if the exception is related to the Entity Framework and, if the migrations context is mismatched with the database, it will redirect to the database deployment page based on the user permissions.

Checking for an exception
Figure 8: Checking for an exception

Note: By using this approach, the application will redirect to the database deployment page when the requested page is trying to talk to the database. If no database calls are present on the requested page, the user will see the requested page even if the database is not up to date with Entity Framework migrations.

Upcoming Enhancements

The current version of EFMigrationsManagerUI package will support a single database or single Entity Framework configuration. If the MVC Web application has multiple Entity Framework configurations/databases, the the current version of the NuGet package will manage only single a configuration. An upcoming version of EFMigrationsManagerUI will support multiple EF configurations.

Examples/Demos

Create the following samples for MVC-based applications that are hosted the source code in the GitHub repository.

1. MVC Application with Windows Authentication

Follow the next steps to set up the working sample:

  1. Download/Clone the source code from the GitHub URL.
  2. Open the project (downloaded in the preceding step) in Visual Studio.
  3. Set ‘Sample_WindowsAuthentication’ as the startup project.
  4. Open the web.config file and update the following AppSetting entry with admin usernames.
       <add key="EFMigrationsManager:AuthorizedUsers"
          value="domain\username" />
    
    Note: For multiple admins, enter comma-separated names.
  5. Update this connection string, if required, to test on a different database or server:
    <connectionStrings>
       <add name="EFEntities" connectionString="data source=.;
          initial catalog=EFDatabase;Integrated Security=SSPI;
          MultipleActiveResultSets=True;App=EntityFramework"
          providerName="System.Data.SqlClient" />
       </connectionStrings>
    

2. MVC Application with Forms Authentication

Create the sample Web application integrated with the Azure active directory. To know more about Azure active directory integration, please read the information from this link.

Follow these steps to set up a working sample:

  1. Download/Clone the source code from this GitHub URL.
  2. Open the project (downloaded in the preceding step) in Visual Studio.
  3. Set ‘FormsAuthentication’ as the startup project.
  4. Open the web.config file and update the following AppSetting entry with admin usernames.
       <add key="EFMigrationsManager:AuthorizedUsers"
          value="username@domain.com" />
    
    Note: For multiple admins, enter comma-separated names.
  5. Update the next connection string, if required, to test on a different database.
    <connectionStrings>
       <add name="EFEntities" connectionString="data source=.;
          initial catalog=EFDatabase;Integrated Security=SSPI;
          MultipleActiveResultSets=True;App=EntityFramework"
          providerName="System.Data.SqlClient" />
    </connectionStrings>
    
  6. Update the following Azure active directory integration-related settings:
       <add key="ida:ClientId" value="" />
       <add key="ida:ClientSecret" value="" />
       <add key="ida:Domain" value="" />
       <add key="ida:TenantId" value="" />
       <add key="ida:PostLogoutRedirectUri" value="" />
    

Conclusion

Entity Framework code-first is very useful in Domain-driven Design and integrating the EFMigrationsManagerUI plug-in will provide a friendly user interface to manage EF migrations. In the next article, we will talk about the user interface to manage migrations for multiple Entity Framework configurations/databases.

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read