This section describes how to set up the Ed-Fi ODS / API v6.0 source cod=
e on a development machine. For those interested in getting an Ed-Fi ODS / =
API instance up and running quickly, but do not have developer tools or exp=
erience we recommend you to consult Getting Started - Binary Installation.<=
/p>
Ensure that the following software is installed and configured:
Visual Studio 2022. Vi=
sual Studio 2022 (Community, Professional, or Enterprise edition) or JetBrains Rider version 2021.3+ (an alternative development envi=
ronment that can be used instead of Visual Studio 2022).
Microsoft SQL Server 2019. Microsoft SQL Server is use=
d to store the data for the Ed-Fi ODS / API. Local installation of Standard=
, Developer, or Enterprise Editions are supported.
Optional PostgreSQL datastore:=20
PostgreSQL 13.x. Postg=
reSQL can be used as the datastore for and Ed-Fi ODS / API instance instead=
of Microsoft SQL Server.
Micr=
osoft SQL Server 2019
Install Microsoft SQL Server 2019:
When prompted, select the following=
features:
Use the default instance named =
;MSSQLSERVER.
Select either Windo=
ws Authentication Mode or Mixed Mode.
In Specify SQL Server administrator=
, click Add Current User.
Install SQL Server Management Studio:
Visual Stu=
dio 2022
Visual Studio 2022(Community edition or higher) is required for a develo=
pment environment.
=
Installing Visual Studio 2022
The instructions below are based on the Visual Studio 2022 Communi=
ty Installer.
1. Launch the installer and make sure the following features are se=
lected:
In the Workloads Tab
.NET Desktop development, and select the following com=
ponents:
ASP.NET and web development
2. Restart your computer (if prompted)
3. Open D=
eveloper Command Prompt for VS2022 as an Administrator, at the command pro=
mpt type gacutil -l envdte to verify EnvDTE is r=
egistered in GAC. If no listings are found, run the following command to ad=
d EnvDTE to GAC.
After installing, check the Visual Studio Start Page an=
d Windows Update for Visual Studio updates.
PostgreSQL Installation (Optional)
Install PostgreSQL 13.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 incl=
ude a GUI to visualize the database (commands are executed via the command =
line using psql). Below is a list of various tools that work:
Installation of PostgreSQL can be done either using the binaries or usin=
g Docker. The recommended solution is to to use the docker install using Li=
nux containers.
Option 1. Installation using PostgreSQL Inst=
aller
Install using the PostgreSQL installer. Version 13.x is compatible with the ODS / API.=20
Create a Docker Compose file (name: docker-compo=
se.yml) to bootstrap PostgreSQL using Linux containers. =
More information on the Docker Compose file can be found on the =
Docker documentation site.
Create an environment file (name: .en=
v) to be consumed by Docker Compose. By default the environment file=
needs to be in the same folder as the Docker Compose file.
PG_PA=
SSWORD=3DP@ssw0rd
Sample files for these can be downloaded from the download panel on the =
right.
Data Retention and Docker Compose
Once you have set up your docker-compose.yml and .env files and placed t=
hem in a folder (e.g., C:\PGDockerSetup), navigate to that folder in P=
owerShell and run docker-compose. This utility reads the&nbs=
p;docker-compose.yml configuration file and runs all of the containers desc=
ribed in that file.
To bring up the environment:
C=
:\PGDockerSetup>docker-compose up -d
To stop the volumes and containers:
C=
:\PGDockerSetup>docker-compose down
To stop the services and remove them, but r=
etain the data in separate volumes:
C=
:\PGDockerSetup>docker-compose down -v
Config=
ure pgpass.conf
Create a pgpass.conf file. Note that the password should be your postgre=
s superuser password and it should match the password in your environment f=
ile.
local=
host:5432:*:postgres:P@ssw0rd
Set the environment variable P=
GPASSFILE 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.<=
/span>
You can test the environment variable =
setup using:
C:\&g=
t; get-item env:pgpassfile
Name Value
---- -----
PGPASSFILE C:\PGDockerSetup\pgpass.conf
Step 3. Download the Ed-Fi ODS / API v6.0 Code
The Ed-Fi ODS / API source code is contained in two Ed-Fi repositor=
ies hosted by GitHub.
Source Code=
Links
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 li=
ne tool to Git Clone each of the repository links described above. It is im=
portant that both repositories are extracted to the same root directory (fo=
r example C:\). When both repositories have been cloned, there will be two =
folders for the ODS / API source code as shown below:
When you clone a repository, ensure that you have the correct tag is che=
cked out in your client before you proceed.
$ git checkout tags/v6.0 -b <branch&g=
t;
If you download the code via a ZIP file, ensure that you check Unblock i=
n the file's Properties dialog to allow the contents of the contained scrip=
ts to execute properly.
Accessing Daily Source
The links above are for the stable release of the ODS / API v6.0. You ca=
n download the links to the very latest daily source code in the deve=
lopment branch:
Some developers prefer simply to download the code rather than perform a=
Git Clone. You can do so by following these instructions:
Navigate to each of the repository links described above (for latest=
release or daily source) and use the Download ZIP&nb=
sp;button to download the repository to your local drive.
In Windows Explorer, right-click on each of the downloaded ZIP files=
and select Extract All=E2=80=A6 Enter C:\ for the targ=
et folder. (You can extract the files to any directory, but these instructi=
ons assume you've extracted to C:\.) The ZIP files contain an embedded fold=
er ending in "-v6.0" (or "-main" if downloading latest daily source). For e=
xample, the "Ed-Fi ODS ZIP" archive contents will be extracted into C:=
\Ed-Fi-ODS-v6.0.
After the extractions are complete, rename the folders to remov=
e the -v6.0 (or "-main") from the folder names. For example, chan=
ge C:\Ed-Fi-ODS-v6.0 to C:\Ed-Fi-ODS.
When the extraction and renaming are complete, there should be two f=
olders 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 extr=
act 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 se=
lect Properties. On the General=
tab, check Unblock to allow the contents o=
f the contained scripts to execute properly.
The dialog box above is from Windows 10. Previous versions of Windows ha=
ve an "Unblock" button in the same location.
Step 4. Prepare the Development Environment
To prepare the development environment, you'll need to follow the proced=
ures described below.
Configure&=
nbsp;MSBuild
Packages compiled from some of the projects are used during the code gen=
eration 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 t=
o the way that MSBuild caches build processes by default to minimize c=
ompile time. Build processes are normally held for reuse for approximately =
10 minutes. To turn off this default behavior when compiling in Visual Stud=
io, the "MSBuildDisableNodeReuse" variable must be set.
To set the "MSBuildDisableNodeReuse" variable globally:
Press the Windows key on your keyboa=
rd, type Environment Variables, select E=
dit the system environment variables, and press Enter=
. This brings up System Properties. Und=
er Advanced, select Environment Variable=
s. (Alternatively, right-click the Start Menu, =
select System, and click on the Advanced=
system settings. Under Advanced, select&nbs=
p;Environment Variables.)
Under User variables, select New...<=
/strong>
For Variable name, enter MSBuildDisa=
bleNodeReuse
For Variable value, enter 1, and press OK.
To turn off this behavior when compiling the solution using MSBuild, inc=
lude 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 Po=
werShell scripts to run on your machine to run the scripts. This can be don=
e by opening a PowerShell console and typing the following command:
Set-E=
xecutionPolicy Unrestricted
Initialize PowerShell Scripts for Development
There are several databases that must be successfully deployed. PowerShe=
ll scripts that initialize all necessary development databases are included=
in the Visual Studio solution. These scripts are enabled for use within Vi=
sual Studio when the Ed-Fi-ODS solution is opened. They may also be lo=
aded for use within a PowerShell console window by running the initial=
ize PowerShell for development script located at:
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 a=
nd a development certificate has been installed, the development environmen=
t may be initialized by navigating to the Ed-Fi-ODS-Implementation folder.<=
/p>
For a SQL Server backing datastore, type the following into a PowerShell=
command prompt:
initd=
ev
For a PostgreSQL, backing datastore, use the following:
initd=
ev -Engine PostgreSQL
This command creates databases, generates code templates, and compiles p=
rojects 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 i=
gnore any messages that appear in the console window.
Initializing the development environment will take several minutes to c=
omplete. Some developers report encountering an error during the initializa=
tion process the first time it is run. This is due to an intermittent timin=
g issue. The issue generally resolves itself when the initdev process is run a second time.
A successful initdev execution will display the t=
asks executed and their duration as shown below:
Another Option for Setting MSBuildDisableNodeReuse
The most convenient method for developers is to set the MSBuildDisableNo=
deReuse variable globally. However, you can also set the variable per comma=
nd prompt session. Both options instruct the compiler to create a new proce=
ss for each build job. As a side effect, this action also releases any reso=
urces that may be held by inactive compiler processes.
If these settings are not applied, Visual Studio or MSBuild may lock res=
ources during build. Restarting Visual Studio (or the command prompt sessio=
n) 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 C=
ommand Prompt Session
If the "MSBuildDisableNodeReuse" variable is set within a command p=
rompt session, the Visual Studio development environment must be launched u=
sing the devenv command (rather than from an icon):
SET M=
SBUILDDISABLENODEREUSE=3D1
Step 5. Build the Visual Studio Solution
To build the solution from within Visual Studio:
Ensure that the MsBuildDisableNodeReuse flag=
is set (see Configure MSBuild, above).
If the above flag has been set globally, start Visual Studio normally. =
Otherwise, open Visual Studio from the Visual Studio Developer Command Prom=
pt (where you set the flag value by typing devenv).
Within Visual Studio, open the "Ed-Fi-Ods.sln" solution file from the C=
:\Ed-Fi-ODS-Implementation\Application directory.
Select Build > Build Solutio=
n (or press Ctrl+Shift=
+B).
C=
ode Generation During Build
The following diagram shows how MeatEd generated artifacts are used to c=
reate 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 i=
t uses to generate data access code. Code generation also depends on the Da=
tabaseViews.generated.json which is generated one time using the "EdFi_Ods_=
Empty" database and subsequently provided by the source code repository.&nb=
sp;
Alternatively Building from the Developer Command P=
rompt
When the =E2=80=9CEdFi_Ods_Empty=E2=80=9D 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 Vi=
sual Studio, as described above, or from a Developer Command Prompt for Vis=
ual Studio using the Windows start menu.
To do a clean build from the command prompt:
Open the Developer Command Prompt for Visual Studio. <=
/li>
Navigate to your C:\Ed-Fi-ODS-Implementation\Application directory.
Issue a command similar to the following:
Msbui=
ld /nr:false /t:clean;build Ed-Fi-Ods.sln
St=
ep 6. Set 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 ru=
nning for the system to be fully functional.
To set the Startup Projects:
Select the Set StartUp Projects=E2=80=A6 con=
text menu by right-clicking on the solution file in the Solution Explorer.<=
br> <=
br>
Within the Startup Project property page, select the Multi=
ple startup projects radio button and enable the following pr=
ojects:=20
EdFi.Ods.SandboxAdmin
EdFi.Ods.SwaggerUI
EdFi.Ods.WebApi
3. Click OK&nb=
sp;to accept the changes to your local development settings.
Step 7=
. Run the Solution
The projects in the Ed-Fi-ODS-Implementation repository are configured t=
o run the desktop version of Internet Information Server (i.e., IIS Express=
). This server is installed with Visual Studio and facilitates easy debuggi=
ng with minimal configuration. After the startup projects are set, you are =
ready to run or debug the Ed-Fi ODS / API.
Running =
the solution
To run the Ed-Fi ODS / API without debugging, press C=
trl+F5.
To interactively debug the Ed-Fi ODS / API solution, press F5 (or press Start in the Standar=
d Toolbar).
N=
otes on Running the Solution
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 E=
xpress. By default, the websites are configured according to the follo=
wing table:
At this point, you're ready to explore the system.
Follow these steps to finish configuring the solution:
Visiting the API Sandbox Administration Portal and logging in with the =
Test User Account
Reviewing the Ed-Fi ODS API Documentation
The Sandbox Administration Portal
The Sandbox Administration Portal is a web application used to create sa=
ndbox databases containing data that can be accessed through the Ed-Fi ODS =
/ API.
Login to Sandbox Administration Portal with Test Admin Account. Login de=
tails can be found in Ed-Fi-ODS-Implementation\Application\EdFi.Ods=
.SandboxAdmin\appsettings.json or alternatively in ap=
psettings.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&nb=
sp;development machines and sandbox instances of the ODS / API, but should =
not be present on production instances. See the Platform Developers' Guide - Dep=
loyment section for details.
The Ed-Fi ODS / API Documentation Web Page
The ODS / API Documentation Web Page provides an overview of the ODS / A=
PI, and links to more detailed API documentation.
The REST interface to the Ed-Fi ODS / API exposes metadata describing th=
e exposed resources as well as the inputs, HTTP verbs, and schema of the ex=
posed entities. This metadata enables a user interface (based on the <=
a class=3D"external-link" href=3D"http://swagger.io/" rel=3D"nofollow">Swag=
ger framework) to display API documentation.
The Swagger-based documentation web page uses a key and secret (typicall=
y the same one used for the Sandbox Administration Portal) to access the da=
ta that has been placed in the corresponding sandbox.
To view the data in your sandbox, click Authorize and e=
nter 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 tok=
en 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 Documentatio=
n Web Page is useful for development machines and sandb=
ox instances of the ODS / API, but is generally not present on production i=
nstances. See the Platform Developers' Guide - Deployment section for d=
etails.
Contents
Find out more about how to begin using the Ed-Fi ODS / <=
/span>API:
Downloads
The following link contains sample docker setup files for PostgreSQL