Conversion to .NET Core 3.1

Owned by Stephen Fuqua
Last updated: Nov 09, 2020 by Vinaya Mayya
5 min read

Abstract

Converting the ODS/API to net core 3.1 requires a paradigm shift on how we migrate. The application started when MVC was in its infancy, and as the framework matured, the ODS/API has not and has implementations from different versions of the MVC framework. For example, our controllers are at different versions of the MVC framework. With the introduction of MVC 6 (net core) some of the legacy implementations has been discontinued. For example, authentication is implemented differently than how we have it in the current ODS/API. With our current implementation, we use an attribute, inheriting from IAuthenticationFilter. This interface is been removed, and in net core we need to implement  middle ware to move forward.

Audience

This document is intended for the development team, and it describes what changes are needed, and what decisions has been made through the migration. The changes are located at:

Process

During the migration, a decision was made to split out the common elements from net framework 4.8 into a common assembly so that items that can be shared between both stacks are isolated. A new net core framework 3.1 assembly is created to implement the net core specific items. Along with a new entry point that is net core specific that utilizes Kestrel, and can be run under IIS or as a console application. This allows for a simpler approach while maintaining the legacy implementation. The unit tests where not addressed during this initial migration, and will need to be in the future.

A heavy reliance on preprocessor directives is use in class where assemblies could not be split. When everything is migrated then these separate assemblies will be consolidated using the preprocessor directives. The standard adopted is:

ConstantUsage
NETFRAMEWORKAll standard net implementations (e.g. net 4.8)
NETSTANDARDAll net standard implementations (e.g. netstandard2.1)
NETCOREAPPAll net core implementations (e.g. netcoreapp3.1)

All C# specific files (.cs) that are NETFRAMEWORK are renamed to (.net.cs) so that they can be identified easily.

Assumptions

  1. The net core application will be run in parallel with the existing application to have a base line for testing.
  2. The net core branch will be brought up to date with the current stable development branch after each sprint.
    1. Ideally code base should be able to be merged into the main development branch at the end of the each sprint (dark shipping).
  3. Features are migrated into one assembly.
  4. Tests will be converted to net core 3.1.
    1. The tests will be removed from the existing net projects.

Resource Requirements

A small team of developers are needed that have the following skill sets: 

  • A strong understanding of object-oriented programming (OOP) principles
  • A strong understanding of SOLID principles
  • A strong understanding of Web API principles.
  • An understanding of .NET framework (net core 2.x and/or 3.x is plus)
  • A strong understanding of an object-oriented programming language (C# or java is a  plus)
  • A strong understanding of Domain Driven Design
  • A strong understanding of testing
  • A willingness to learn, and work with a virtual team.
  • A strong understanding of agile methods and principles.
  • Proficiency with git commands and github workflows 

Stories

The following list is the likely stores required so the application can be migrated to net core in parallel with the current application.

StoriesPriorityT-Shirt SizeChanges RequiredStatusNotes
Decision on IOC container

MUST HAVE

SMALL

  • Research other IoC containers to find one that is compatible with net core 3.1

DONE


Migrate Codegen to 3.1

MUST HAVE

MEDIUM

  • Convert the Codegen Utility to netcore 3.1.
    • Update container to Autofac
    • Update project to netcore 3.1

DONE


Package Migration

MUST HAVE

MEDIUM

  • Update the solution to packages that are supported by net core 3.1

DONE


Migrate Common

MUST HAVE

SMALL

  • Update Ed-Fi Common  and EdFi.Ods.Common to support net standard 2.1

DONE


Api Project for Net Core

MUST HAVE

LARGE

  • Create a net core 3.1 specific API project to bring Web API specific implementations. (EdFi.Ods.Api.Netcore)
  • Create a new common assembly that can be shared by the existing API and new API (EdFi.Ods.Api.Common)

DONE


Entry Point for Net Core

MUST HAVE

SMALL

  • Add a net core application that will run the API from command line and/or IIS. (EdFi.Ods.WebApi.Netcore)

DONE


Convert Controllers

MUST HAVE

LARGE

  • Convert the Web API controllers to netcore 3.1
    • EdFiControllerBase → DataManagmentControllerBase
    • AggregateDependencyController
    • CompositeResourceContoller
    • IdentitiesController
    • TokenController
    • VersionContoller
  • Update Codegen controllers generator so that the legacy net 48 controllers are still built, along with the net core controllers.

DONE


Refactor into common items

MUST HAVE

LARGE

  • Refactor common items of net 48 and net core Web API

DONE


Implement container registration

MUST HAVE

LARGE

  • Create new installers for container registration for the net core Web API
    • Net core specific only.

DONE


Update projects to net core and/or net standard

MUST HAVE

LARGE

  • Update projects in the solution to support either net standard 2.1 and/or net core app 3.1

DONE


Routing Approach

MUST HAVE

MEDIUM

  • Implement a method of defining routes for the controllers that is easily maintained.

DONE


Add nHibernate support (Data management)

MUST HAVE

MEDIUM

  • Add nHibernate support to the net core application. 
    • Update container registration

DONE


Add Entity Framework support

MUST HAVE

MEDIUM

  • Update usages of Entity Framework
    • Add support for asynchronous methods where necessary 
    • Update container registration

DONE


Extensions feature

MUST HAVE

SMALL

  • Add support for the extensions feature in the net core Web API
    • Should be turned on or off via a configuration flag
    • Add Open API Metadata support

DONE


Authentication and OAuth

MUST HAVE

MEDIUM

  • Add a Web API convention to support authorization
  • Update token controller to work asynchronously

DONE


Open Api Metadata Feature

MUST HAVE

XTRA LARGE

  • Add a Web API convention for routing
  • Add Web API middle ware for serving the generated document. (replaced IHttpHandler in net 48 Web API project)
  • Fix Open API Metadata 

DONE


Aggregate Dependencies Feature

MUST HAVE

XTRA SMALL

  • Enable aggregate dependencies feature in the net core Web API
    • Update container registration

DONE


Plugins

MUST HAVE

SMALL

  • Enable plugins feature in the net core Web API
    • Update container registration
    • Should load plugins from a folder

DONE

Requires more testing with a plugin assembly.
Composites Feature

MUST HAVE

SMALL

  • Enable composites feature in the net core Web API
    • Update container registration
    • Should be turned on or off via a configuration flag
    • Add Open API Metadata support

DONE


Change Queries

MUST HAVE

SMALL

  • Enable changes feature in the net core Web API
    • Update container registration
    • Should be turn ed on or off via a configuration flag
    • Fix any queries to be asynchronous
    • Add Open API Metadata support
    • Change Queries remain in a separate assembly to support MetaEd

DONE


Profiles Feature

MUST HAVE

LARGE

  • Enable profiles feature in the net core Web API
    • Update container registration
    • Should be turned on or off via a configuration flag
    • Add Open API Metadata support
  • Dynamic profiles  ODS-3081 - Getting issue details... STATUS  would be arguably the better path although more analysis can be done to figure out how to route to the profile specific controller based on content type.  
  • See also  ODS-3940 - Getting issue details... STATUS  for proposed simplifications that deprecate content type for profiles.

DONE


Identity Management Feature

MUST HAVE

SMALL

  • Enable Identity Management feature in the net core Web API
    • Update container registration
    • Add container support for sample implementation
    • Should be turned on or off via a configuration flag
    • Update container registration
    • Update documentation

DONE


Unique Id Integration Feature

MUST HAVE

SMALL

  • Enable unique id integration feature in the net coreWeb API
    • Update container registration
      • Add container registration for sample implementation
      • Update documentation
    • Should be turned on or off via a configuration flag
    • Add Open API Metadata support

DONE


Record Ownership Feature

MUST HAVE

SMALL

  • Enable unique id integration feature in the net core Web API
    • Update container registration
    • Should be turned on or off via a configuration flag
    • Add Open API  Metadata support

DONE


Convert Swagger UI project to net core 3.1

MUST HAVE

MEDIUM

DONE


Convert Sandbox Admin Web 

MUST HAVE

LARGE

  • Convert the sandbox admin web application to net core 3.1
  • This is a conversion of the web application to the new net core MVC format. 
    • Risks are that some of the used packages may not be available, and some rewrite of that code may be necessary.
  • Note more analysis is still needed and the estimate include that analysis
  • This is a conservative estimate.

DONE


Convert Test projects

MUST HAVE

LARGE

  • Convert the test projects to net core 3.1. Remove the dependencies on the legacy code, and reference the new net core code.
  • The biggest challenge will be the EdFi.Ods.Webservice test project.

DONE


Convert Test Harness to net core 3.1

MUST HAVE

SMALL

  • Convert the application to a net core application. 

DONE


Regression Testing

MUST HAVE

MEDIUM

to

XTRA LARGE

  • Validation of the application is at parity the the legacy application
  • Should at least run performance testing

DONE


Deprecation of the net 48 application

MUST HAVE

MEDIUM

  • Remove the legacy code within the solution

DONE


Docker Developer Environment

NICE TO HAVE


  • Build and testing using docker

NOT STARTED


Docker Deployment Environment

MUST HAVE


IN PROGRESS


TeamCity Build

MUST HAVE



DONE


JSON config transformation in powershell

MUST HAVE


DONE


Web config setup for IIS hosting

MUST HAVE



DONE