This section describes how to set up the Ed-Fi ODS / API v3.1 on a development machine.

The steps can be summarized as:

Detail on each step follows.

Step 1. Obtain an Ed-Fi Technology License

The Ed-Fi License is free and available online. If you haven't done so already, visit the Ed-Fi.org licensing section for details and a link to get started.

Step 2. Install and Configure Windows Components

Ensure that the following components are installed:

• PowerShell 5.0. PowerShell is used to initialize the development environment.
• Microsoft Message Queue Server Core. MSMQ Server Core is used to manage asynchronous messaging for the Bulk Load API of the Ed-Fi / ODS API.
• .NET Framework 3.5. The .NET Framework 3.5 is required for Microsoft SQL Server.
• .NET Framework 4.62 Developer Pack. The .NET Framework 4.6.2 Developer Pack is required for compiling the solution.
   

Step 3. Install and Configure Required Software

Ensure that the following software is installed and configured:

• Java Runtime Environment 8 or Higher. The Profiles feature of the Ed-Fi ODS / API ships with integration tests that generate a version of the Ed-Fi ODS / API SDK. This generation step requires Java Runtime Environment version 8 or higher.
• Microsoft SQL Server 2014. Microsoft SQL Server is used to store the data for the Ed-Fi ODS / API. Local installation of Standard, Developer, or Enterprise Editions with Service Pack 2 or higher are supported. Using a remote instance of Microsoft SQL Server is not currently supported.

• Visual Studio 2017 or 2015. Visual Studio 2017 (Community edition or higher) or Visual Studio 2015 (Professional edition or higher) is required for a development environment.

  
  

Step 4. Download the Ed-Fi ODS / API v3.1 Code

Before you begin this step, make sure you have a license and a login to access the Ed-Fi Alliance source code repository in GitHub. The Ed-Fi ODS / API source code is contained in three Ed-Fi repositories hosted by GitHub. 

Source Code Links

The Ed-Fi ODS / API can be found in the repository links below:

• Ed-Fi-Common/v3.1.1

• Ed-Fi-ODS/v3.1.1

• Ed-Fi-ODS-Implementation/v3.1.1

Use a Git client (such as GitHub Desktop) or a Git command line tool to Git Clone each of the repository links described above. It is important that all three repositories are extracted to the same root directory (for example C:\). When all repositories have been cloned, there will be three folders for the ODS / API source code as shown below:

Step 5. Prepare the Development Environment

To prepare the development environment, you'll need to follow the procedures described below.

Configure MSBuild

Packages compiled from some of the projects are used during the code generation of later projects, and there is a potential for earlier packages to be locked if the solution is recompiled in rapid succession. This is due to the way that MSBuild caches build processes by default to minimize compile time. Build processes are normally held for reuse for approximately 10 minutes. To turn off this default behavior when compiling in Visual Studio, the "MSBuildDisableNodeReuse" variable must be set.

To set the "MSBuildDisableNodeReuse" variable globally:

1. Press the Windows key on your keyboard, type Environment Variables, select Edit the system environment variables, and press Enter. This brings up System Properties. Under Advanced, select Environment Variables. (Alternately, right-click the Start Menu, select System, and click on the Advanced system settings. Under Advanced, select Environment Variables.)
2. Under User variables, Select New...
   
3. For Variable name, enter MSBuildDisableNodeReuse
4. For Variable value, enter 1, and press OK.
   

To turn off this behavior when compiling the solution using MSBuild, include the following compiler flag: /nr:false. 

Verify PowerShell Script Permissions

When opening PowerShell, ensure that Run as Administrator is selected. You may need to change the execution policy for unsigned PowerShell scripts to run on your machine to run the scripts. This can be done by opening a PowerShell console and typing the following command:

Set-ExecutionPolicy Unrestricted

Initialize PowerShell Scripts for Development

There are several databases that must be successfully deployed. PowerShell scripts that initialize all necessary development databases are included in the Visual Studio solution. These scripts are enabled for use within Visual Studio when the Ed-Fi-ODS solution is opened. They may also be loaded for use within a PowerShell console window by running the initialize PowerShell for development script located at:

C:\Ed-Fi-ODS-Implementation\Initialize-PowershellForDevelopment.ps1

When the scripts are loaded, you should see the results shown below:

Initialize the Development Environment

Once the PowerShell scripts for development have been loaded, the development environment may be initialized by typing the following into a PowerShell command prompt:

initdev

This command creates databases, generates code templates, and compiles projects in the solution. Some considerations while running the script:

• The initdev script may not finish with a command prompt when it is automatically loaded with the solution in Visual Studio in some circumstances. Simply press Enter, and ignore any messages that appear in the console window.
• Initializing the development environment will take several minutes to complete. Some developers report encountering an error during the initialization process the first time it is run. This is due to an intermittent timing issue. The issue generally resolves itself when the initdev process is run a second time.

A successful initdev execution will display the tasks executed and their duration as shown below:

SET MSBUILDDISABLENODEREUSE=1

Step 6. Build the Visual Studio Solution

To build the solution from within Visual Studio:

1. Ensure that the MsBuildDisableNodeReuse flag is set (see Configure MSBuild, above).
2. If the above flag has been set globally, start Visual Studio normally. Otherwise, open Visual Studio from the Visual Studio Developer Command Prompt (where you set the flag value by typing devenv).
3. Within Visual Studio, open the "Ed-Fi-Ods.sln" solution file from the C:\Ed-Fi-ODS-Implementation\Application directory.
4. Select Build > Build Solution (or press Ctrl+Shift+B).
    

Msbuild /nr:false /t:clean;build Ed-Fi-Ods.sln

Step 7. Set the Startup Projects

The Visual Studio Solution for the Ed-Fi ODS / API consists of several "Startup Projects" that work together. Each of these projects needs to be running for the system to be fully functional.

To set the Startup Projects:

1. Select the Set StartUp Projects… context menu by right-clicking on the solution file in the Solution Explorer.
   
   
   
2. Within the Startup Project property page, select the Multiple startup projects radio button and enable the following projects:
   • EdFi.Ods.Admin.Web
   • EdFi.Ods.SwaggerUI
   • EdFi.Ods.WebApi
   
   

The Upload and Bulk workers work in conjunction with the bulk load API. They monitor message queues containing instructions to asynchronously reassemble the uploaded file segments and process the assembled bulk data. If you will be performing bulk operations, you may choose to set the startup project action to Start for the following projects: 

• • EdFi.Ods.BulkLoad.Services.Windows.BulkWorker
  • EdFi.Ods.BulkLoad.Services.Windows.UploadWorker

Alternatively, you can start these projects on demand after loading the files.

3.   Click OK to accept the changes to your local development settings.

Step 8. Set the Start Options for EdFi.Ods.WebApi

1. Select the Properties context menu by right-clicking on the EdFi.Ods.WebApi project in Solution Explorer.
   
   
   
   
2. Within the Project Properties page, go to the Web tab and change the Start Action to Don't open a page. Wait for a request from an external application.
   
   

Step 9. Build and Run the Solution

The projects in the Ed-Fi-ODS-Implementation repository are configured to run the desktop version of Internet Information Server (i.e., IIS Express). This server is installed with Visual Studio and facilitates easy debugging with minimal configuration. After the startup projects are set, you are ready to run or debug the Ed-Fi ODS / API.

• To run the Ed-Fi ODS / API without debugging, press Ctrl+F5.
• To interactively debug the Ed-Fi ODS / API solution, press F5 (or press Start in the Standard Toolbar).

The first time you build the solution, you may get a build error related to the Ed-Fi-Common project. If this occurs, simply building the solution again will generally result in a successful build.

The solution builds and starts each of the projects that were added to the startup projects list. Each web application starts an instance of IIS Express. By default, the websites are configured according to the following table:

At this point, you're ready to explore the system.