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:

Ed-Fi-ODS (main branch)
Ed-Fi-ODS-Implementation (main branch)

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:

Constant	Usage
NETFRAMEWORK	All standard net implementations (e.g. net 4.8)
NETSTANDARD	All net standard implementations (e.g. netstandard2.1)
NETCOREAPP	All 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

The net core application will be run in parallel with the existing application to have a base line for testing.
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).
Features are migrated into one assembly.
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.

Stories	Priority	T-Shirt Size	Changes Required	Status	Notes
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	Convert the SwaggerUI web project to netcore 3.1 Update the swagger ui assembly that is embedded in (https://github.com/Ed-Fi-Alliance/swagger-ui) to net core 3.1 Convert the web project to net core 3.1	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		Ability to deploy on docker and/or Kubernetes See Ed-Fi in Containers	IN PROGRESS
TeamCity Build	MUST HAVE			DONE
JSON config transformation in powershell	MUST HAVE		See JSON Config Transformation	DONE
Web config setup for IIS hosting	MUST HAVE			DONE

Ed-Fi Technical Designs

Conversion to .NET Core 3.1