In this example, we will create a new domain entity called StudentTransportation. This entity will be an extension to the Student Enrollment interchange and will be exposed in Ed-Fi ODS / API through a new API resource called studentTransportations. 

It is assumed that the Ed-Fi ODS / API has been successfully downloaded and is running as in a local environment per the instructions in the Getting Started documentation.  

The steps can be summarized as:

Each step is outlined in detail, below. 

Step 1. Author C# Extension Files

Set Up the Project Template

1. Open a PowerShell instance and navigate to the location of the Extension templates (i.e., <source directory>\Ed-Fi-ODS\Utilities\VisualStudioProjectTemplates\Ed-Fi-Extension-Templates).

   1. Execute the PowerShell script InitTemplates.ps1 by executing the command: 

      .\InitTemplates.ps1

   2. When prompted, enter Extension1. This value will been appended to the project base name when importing the templates into Visual Studio.
2. Determine the location of the Visual Studio ProjectTemplates folder on your machine as follows:
   • Open Visual Studio and go to Tools > Options > Projects and Solutions. 
   • Get the value in the "User project templates locations". (The default location is C:\Users\[User]\Documents\Visual Studio 2015\Templates\ProjectTemplates).
3. Copy the following folders (located under ...\Ed-Fi_Extension-Templates) to the  Visual Studio Project Templates folder (determined in 2 above). 
   
   • Ed-Fi-Extension-Assembly-Template
   • Ed-Fi-Extension-SemanticModel-Assembly-Template
4. Verify the Ed-Fi Extension Templates project type has been registered, by selecting File > New > Project and navigating to Installed-Templates-Visual C#.
   
   

Install the New Extension Projects

1. To add a project to your Ed-Fi-Ods Visual Studio Solution, right-click on the Ed-Fi Extensions Folder. Select Add > New Project.
   
   
   
   

2. Select  the Ed-Fi Extension Assembly Template option. In the Name: field enter EdFi.Ods.Standard.Extensions.Extension1 and click OK. 
   
   

3. Add another project to the Ed-Fi Extensions folder. This time, select the Ed-Fi Extension Semantic Model Assembly Template option. In the Name: field enter EdFi.Ods.Standard.SemanticModels.Extensions.Extension1 and click OK. 

Edit the Extension Projects

Locate the DomainMetadata-Extension.xml file within the EdFi.Ods.Standard.SemanticModels.Extensions.Extension1\SupportingArtifacts\Metadata folder. This file defines the extensions that exist for the new project. Example values have been provided for convenience, and need to be modified as follows:

1. Replace schema="{Physical Schema Value}" to match the physical database schema (in this example, schema="extension").

2. Replace the sample aggregate metadata to represent StudentTransportation:

   DomainMetadata-Extension.xml

   <AggregateExtensions logicalSchema="Extension1" schema="extension1">
     <Aggregate root="StudentTransportation">
       <Entity table="StudentTransportation" />
     </Aggregate>
   </AggregateExtensions>

Step 2. Integrate Extension into the Solution

To integrate the extension into the solution, perform the following tasks:

1. Locate the EdFi.Ods.WebApi project, within the "Entry Points" folder. Right-click, select Add > Reference..., then select the EdFi.Ods.Standard.Extensions.Extension1 and EdFi.Ods.Standard.SemanticModels.Extensions.Extension1 projects.

   

2. Open the EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs file

   1. Add a line to include the Extension1 assembly:

      EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs

      using EdFi.Ods.Standard.Extensions.Extension1;

   2. Locate the EnsureAssembliesLoaded method in the same file and add a line for the new extension assembly marker to ensure it is loaded at runtime.

      EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs

      AssemblyLoader.EnsureLoaded<Marker_EdFi_Ods_Standard_Extensions_Extension1>();

3. Right-click the solution and select Project Dependencies. Select EdFi.Ods.Admin.Models in the project dropdown and add a dependency on the EdFi.Ods.Standard.SemanticModels.Extensions.Extension1 project.
   

Step 3. Author Database Schema Extensions

First, create an extension SQL script called 1002-EdFi_Ods_Extension1.sql and place it in the C:\Ed-Fi-ODS-Implementation\Database\Structure\EdFi folder. This script defines the database schema for the extension. 

Next, author the database schema extensions in the 1002-EdFi_Ods_Extension1.sql file. The SQL script is downloadable via the link on this page, or you can use the source below:

IF NOT EXISTS (SELECT * FROM sys.schemas WHERE name = 'extension1')
BEGIN
EXEC sp_executesql N'CREATE SCHEMA [extension1]
    AUTHORIZATION [dbo];'
END
GO

------------------------------------
-- Create a Student entity extension
------------------------------------
PRINT N'Creating [extension1].[StudentTransportation]...';
GO

CREATE TABLE extension1.StudentTransportation (
    Id uniqueidentifier NOT NULL CONSTRAINT StudentTransportation_DF_Id DEFAULT newid(),
    SchoolId INT NOT NULL,
    StudentUSI INT NOT NULL,
    AMBusNumber VARCHAR(6) CONSTRAINT StudentTransportation_DF_AMBusNumber DEFAULT '-' NOT NULL,
    PMBusNumber VARCHAR(6) CONSTRAINT StudentTransportation_DF_PMBusNumber DEFAULT '-' NOT NULL,
    EstimatedMilesFromSchool DECIMAL(5,2) NOT NULL,
    CreateDate datetime NOT NULL CONSTRAINT StudentTransportation_DF_CreateDate DEFAULT getdate(),
    LastModifiedDate datetime NOT NULL CONSTRAINT StudentTransportation_DF_LastModifiedDate DEFAULT getdate(),
    CONSTRAINT StudentTransportation_PK PRIMARY KEY CLUSTERED (SchoolId,StudentUSI,AMBusNumber,PMBusNumber),
    CONSTRAINT FK_StudentTransportation_SchoolId FOREIGN KEY (SchoolId) REFERENCES edfi.School (SchoolId),
    CONSTRAINT FK_StudentTransportation_StudentUSI FOREIGN KEY (StudentUSI) REFERENCES edfi.Student (StudentUSI)
);     

CREATE UNIQUE NONCLUSTERED INDEX GUID_StudentTransportation ON extension1.StudentTransportation (Id);
GO

EXEC sys.sp_addextendedproperty 'MS_Description', 'A designation of the transportation a student uses to get to and from school.', 'schema', 'extension1', 'table', 'StudentTransportation'
GO

Step 4. Author Bulk/XSD Schema Extensions

Support for bulk loading of data into extension entities is not supported in the Technical Preview release. This capability is currently under development, tracked by ODS-1750 - ODS_API 3.0: Support for Bulk Loading Extension Entities OPEN .

Step 5. Run Code Generation and Verify Changes 

Save all modified files, close Ed-Fi-ODS.sln, and re-run the code generation steps outlined in the Getting Started Guide, (i.e., from a PowerShell prompt run Initialize-PowershellForDevelopment.ps script, followed by the initdev command). Then, run the application and view the Ed-Fi ODS / API in the Swagger UI. The following new API resource should be visible: