This section describes how to set up the Ed-Fi ODS / API v3.2 on a development machine.
The steps can be summarized as:
Detail on each step follows.
For those interested in getting an Ed-Fi ODS/API instance up and running quickly, but do not have developer expertise, we recommend you consult the Ed-Fi Exchange, which provides a number of alternatives for installing the Ed-Fi ODS, including Windows Installers (for on-premise / Virtual Machine targets, as well as support for deploying into public cloud (Amazon Web Services, Google Cloud, and Microsoft Azure)
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.
Ensure that the following components are installed:
Verify that PowerShell 5.0 or above is installed:
Microsoft Message Queue Server Core
Verify that MSMQ Server Core is installed:
.NET Framework 3.5
Verify that .NET Framework 3.5 is installed:
Alternatively, download the .NET Framework 3.5 installer.
.NET Framework 4.6.2 Developer Pack
Download and install the .NET Framework 4.6.2 Developer Pack.
.NET CORE 2.2 SDK
Download and install .NET Core SDK 2.2.109 (Compatible with Visual Studio 2017).
Ensure that the following software is installed and configured:
Visual Studio 2017. Visual Studio 2017 version 15.9.11+ (Community, Professional or Enterprise edition) or JetBrains Rider version 2019.1+ (an alternative development environment that can be used instead of Visual Studio 2017).
Java Runtime Environment
Install the latest version of the Java Runtime Environment.
Microsoft SQL Server 2016
Install Microsoft SQL Server 2016:
Install SQL Server Management Studio:
Visual Studio 2017
Visual Studio 2017 (Community edition or higher) is required for a development environment.
Installing Visual Studio 2017
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.
The Ed-Fi ODS / API can be found in the repository links below:
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:
When you clone a repository, ensure that you have the correct tag or branch checked out in your client before you proceed.
If you download the code via a ZIP file, ensure that you check Unblock in the file's Properties dialog to allow the contents of the contained scripts to execute properly.
Accessing Daily Source
The links above are for the stable release of the ODS / API v3.2. You can download the links to the very latest daily source code in the development branch:
Alternate Method for Code Download
Some developers prefer simply to download the code rather than perform a Git Clone. You can do so by following these instructions:
Troubleshooting the File Extract
The steps above work for most users. However, depending on your Windows security settings, you might get a warning or error when attempting to extract the downloaded ZIP files. If this happens to you, the fix is easy:
In Windows Explorer, right-click each of the downloaded ZIP files and select Properties. On the General tab, check Unblock to allow the contents of the contained scripts to execute properly.
The dialog box above is from Windows 10. Previous versions of Windows have an "Unblock" button in the same location.
To prepare the development environment, you'll need to follow the procedures described below.
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:
To turn off this behavior when compiling the solution using MSBuild, include the following compiler flag: /nr:false.
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:
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:
When the scripts are loaded, you should see the results shown below:
Once the PowerShell scripts for development have been loaded and a development certificate has been installed, the development environment may be initialized by navigating to the Ed-Fi-ODS-Implementation folder and typing the following into a PowerShell command prompt:
This command creates databases, generates code templates, and compiles projects in the solution. Some considerations while running the script:
initdevscript 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.
initdevprocess is run a second time.
initdev execution will display the tasks executed and their duration as shown below:
Another Option for Setting MSBuildDisableNodeReuse
The most convenient method for developers is to set the MSBuildDisableNodeReuse variable globally. However, you can also set the variable per command prompt session. Both options instruct the compiler to create a new process for each build job. As a side effect, this action also releases any resources that may be held by inactive compiler processes.
If these settings are not applied, Visual Studio or MSBuild may lock resources during build. Restarting Visual Studio (or the command prompt session) will resolve the problem for the first build after the restart. Waiting for up to 15 minutes between builds will also achieve this.
Set "MSBuildDisableNodeReuse" per Command Prompt Session
If the "MSBuildDisableNodeReuse" variable is set within a command prompt session, the Visual Studio development environment must be launched using the devenv command (rather than from an icon):
To build the solution from within Visual Studio:
Code Generation During Build
The following diagram shows how the XML schema and empty ODS Database are used to create the API for the Ed-Fi ODS using code generators within the solution. The presence of the "EdFi_Ods_Empty" database is necessary because the code generation uses the database to understand the structure that it uses to generate data access code.
Alternatively Building from the Developer Command Prompt
When the “EdFi_Ods_Empty” database has been created (by running the
To do a clean build from the command prompt:
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:
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:
Alternatively, you can start these projects on demand after loading the files.
3. Click OK to accept the changes to your local development settings.
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.
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:
Ed-Fi ODS API
Ed-Fi ODS API Documentation
At this point, you're ready to explore the system.
Follow these steps to finish configuring the solution:
The Sandbox Administration Portal
The Sandbox Administration Portal is a web application used to create sandbox databases containing data that can be accessed through the Ed-Fi ODS / API.
Login to Sandbox Administration Portal with Test Admin Account. Login details can be found in Ed-Fi-ODS-Implementation\Application\EdFi.Ods.Admin.Web\AdminCredential.config file. We recommend that you change your password as soon as you log in.
As the name implies, Sandbox Administration Portal is useful for development machines and sandbox instances of the ODS / API, but should not be present on production instances. See the Platform Developers' Guide - Deployment section for details.
The Ed-Fi ODS / API Documentation Web Page
The ODS / API Documentation Web Page provides an overview of the ODS / API, and links to more detailed API documentation.
The REST interface to the Ed-Fi ODS / API exposes metadata describing the exposed resources as well as the inputs, HTTP verbs, and schema of the exposed entities. This metadata enables a user interface (based on the Swagger framework) to display API documentation.
The Swagger-based documentation web page uses a key and secret (typically the same one used for the Sandbox Administration Portal) to access the data that has been placed in the corresponding sandbox.
To view the data in your sandbox, click Authorize and enter the key and secret in the appropriate fields and retrieve a token (the key and secret values for the default sandbox are pre-populated). This token is used throughout your session to access your sandbox. This is the same process used by other applications to access their data.
Similar to the Sandbox Administration Portal, the ODS / API Documentation Web Page is useful for development machines and sandbox instances of the ODS / API, but is generally not present on production instances. See the Platform Developers' Guide - Deployment section for details.