PowerShell 5.0

Verify that PowerShell 5.0 or above is installed:

1. Press the Windows key  on your keyboard, type PowerShell, select Windows PowerShell, and press Enter.
2. Type $PSVersionTable.PSVersion, and press Enter. 
   
3. If the required version is not installed, download Windows Management Framework 5.0, which includes PowerShell 5.0.

.NET CORE 3.1 SDK

Download and install .NET Core SDK 3.1.301 (Compatible with Visual Studio 2019).

Microsoft SQL Server 2016 or 2017

Install Microsoft SQL Server 2016:

1. When prompted, select the following features:
   
2. Use the default instance named MSSQLSERVER.
   

3. Select either Windows Authentication Mode or Mixed Mode.
   

   Note
   Mixed Mode may be preferred if you also intend to install the Ed-Fi Dashboards. Mixed Mode can be enabled later by following the Change Server Authentication Mode instructions.

   
   

4. In Specify SQL Server administrator, click Add Current User.

Install SQL Server Management Studio:

Visual Studio 2019

Visual Studio 2019 (Community edition or higher) is required for a development environment.

Installing Visual Studio 2019

PostgreSQL Installation (Optional)

Install PostgreSQL 11.x on port 5432 if you intend to use PostgreSQL as a backing datastore for the ODS / API.

PostgreSQL Visualization Tool

Unlike SQL Server, PostgreSQL does not include a GUI to visualize the database (commands are executed via the command line using psql). Below is a list of various tools that work:

• pgAdmin
• DBeaver
• OmniDB
• DataGrip

Install PostgreSQL

Installation of PostgreSQL can be done either using the binaries or using Docker. The recommended solution is to to use the docker install using Linux containers.

Option 1. Installation using PostgreSQL Installer

Option 2. PostgreSQL Installation with Docker

version: '3.7'

services:
    pg11:
        image: postgres:11-alpine
        container_name: pg11
        volumes:
            - pg11-database:/var/lib/postgresql/data
        ports:
            - 5432:5432
        environment:
            - POSTGRES_PASSWORD=${PG_PASSWORD}
        restart: on-failure

volumes:
    pg11-database:
        driver: local
        name: pg11-database

PG_PASSWORD=P@ssw0rd

C:\PGDockerSetup>docker-compose up -d

C:\PGDockerSetup>docker-compose down

C:\PGDockerSetup>docker-compose down -v

Configure pgpass.conf

Create a pgpass.conf file. Note that the password should be your postgres superuser password and it should match the password in your environment file.

localhost:5432:*:postgres:P@ssw0rd

Set the environment variable PGPASSFILE to the location of the pgpass file that was created, which is the recommended approach. Optionally, the file can be saved in %APPDATA%/postgresql/pgpass.conf.

You can test the environment variable setup using:  

C:\> get-item env:pgpassfile

Name                           Value
----                           -----
PGPASSFILE                     C:\PGDockerSetup\pgpass.conf

When you clone a repository, ensure that you have the correct tag is checked out in your client before you proceed.

$ git checkout tags/v5.2-patch1 -b <branch>

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 v5.2. You can download the links to the very latest daily source code in the development branch:

• Ed-Fi-ODS/main

• Ed-Fi-ODS-Implementation/main

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:

1. Navigate to each of the repository links described above (for latest release or daily source) and use the Download ZIP button to download the repository to your local drive.

   

2. In Windows Explorer, right-click on each of the downloaded ZIP files and select Extract All… Enter C:\ for the target folder. (You can extract the files to any directory, but these instructions assume you've extracted to C:\.) The ZIP files contain an embedded folder ending in "-v5.2" (or "-main" if downloading latest daily source). For example, the "Ed-Fi ODS ZIP" archive contents will be extracted into C:\Ed-Fi-ODS-v5.2.

3. After the extractions are complete, rename the folders to remove the -v5.2 (or "-main") from the folder names. For example, change C:\Ed-Fi-ODS-v5.2 to C:\Ed-Fi-ODS. 

4. When the extraction and renaming are complete, there should be two folders for the ODS / API source code as shown below:

   

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.

Set-ExecutionPolicy Unrestricted

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

initdev

initdev -Engine PostgreSQL

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):

SET MSBUILDDISABLENODEREUSE=1

Code Generation During Build

The following diagram shows how MeatEd generated artifacts are used to create the API for the Ed-Fi ODS using code generators within the solution. Code generation uses Api Model JSON file to understand the structure that it uses to generate data access code. Code generation also depends on the DatabaseViews.generated.json which is generated one time using the "EdFi_Ods_Empty" database and subsequently provided by the source code repository. 

Alternatively Building from the Developer Command Prompt

When the “EdFi_Ods_Empty” database has been created (by running the initdev PowerShell command in the previous step), there are two ways to build the solution. The solution can be built from Visual Studio, as described above, or from a Developer Command Prompt for Visual Studio using the Windows start menu.

To do a clean build from the command prompt:

1. Open the Developer Command Prompt for Visual Studio.
   
2. Navigate to your C:\Ed-Fi-ODS-Implementation\Application directory.
3. Issue a command similar to the following:

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

Follow these steps to finish configuring the solution:

1. Visiting the API Sandbox Administration Portal and logging in with the Test User Account
2. Reviewing the Ed-Fi ODS API Documentation

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.SandboxAdmin\appsettings.json or alternatively in appsettings.development.json 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.

Image RemovedImage Added

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.