This example outlines the steps necessary to integrate and activate Ed-Fi Profile definitions for use in an Ed-Fi ODS / API. It is assumed that the Ed-Fi ODS / API has been successfully set up and is running in a local environment per the instructions in the Getting Started documentation.
The steps in Visual Studio can be summarized as:
Detail on each step follows.
Step 1. Create the Profiles Project
Create the Visual Studio Project
- Add a Profiles Project Using the Visual Studio Project Template. Visual Studio Project Template can be installed by following steps in Getting Started - Project Templates Installation section of this documentation.
- Add the Profiles project, right-click on the "Profiles" folder and selecting File > Add > New Project...
- In the "Add New Project" dialog, find the "Ed-Fi API Profiles Project Template" entry at the bottom of the Visual C# section, as shown below. Make sure you choose Microsoft .NET Framework 4.6.2 or above.
- Enter the project name for the new project and click OK. The suggested naming convention for this type of project is something like EdFi.Ods.Profiles.MyProfiles.
Update the Marker Interface File. To integrate the Profiles with the API, start by ensuring you have a marker interface in the root of your Profiles project.
This interface is an idiom used in the Ed-Fi Visual Studio Solution to enable a strongly typed mechanism for obtaining a reference to the .NET assembly. If you used the Visual Studio Project template to create your profile, a file will already exist — but you'll need to rename the interface and the file to match the convention (e.g., Marker_EdFi_Ods_Profiles_MyProfiles.cs). The marker interface file should have the following code:
Add references to extension entities. If any of the Profile resources in the Profiles.xml document are extended, or extension entities are being constrained by a particular Profile, then project references are needed for the assemblies containing the extensions. As an example, in the Profile.xml file created by the Visual Studio template, School-and-Student-Sample has the resource School, which is extended in the EdFi.Ods.Extensions.Sample and EdFi.Ods.Extensions.GrandBend sample extensions. A hard project reference to this Ed-Fi Extension assembly must be added to the newly created Profile project.
- Review and modify Profiles.xml file. The Visual Studio Project Template creates a sample Profiles.xml file. You should open it and modify it to meet the needs of your Profile. Consult API Profiles for guidance.
- Save the Project.
Step 2. Integrate Profiles into the Solution
To integrate the Profiles into the solution, perform the following tasks in the EdFi.Ods.WebApi project (located in the "Entry Points" folder):
- Add a reference to the Profiles project you constructed in the previous step.
- Open the EdFi.Ods.WebApi.Startup.ConfigurationSpecificSandboxStartup.cs file and add the code in the following steps.
Add a line to include the new Profiles assembly:
Locate the Configuration method in the same file and add a line for the new Profiles assembly marker to ensure it is loaded at runtime:
Step 3. Run Code Generation and Verify Changes
Save all modified files, close the Ed-Fi-ODS Visual Studio Solution, then 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 using Swagger.
The new Profile should be visible:
Profiles in Use
This section covers additional information and settings useful after development is complete.
Confirming Profile Settings
Profile settings are flexible. With this flexibility comes some complexity — so platform hosts will want to confirm that the deployed API Profiles behave as expected, exposing exactly the right resources. This can be done manually or using an SDK created by code generation techniques.
Adding Profiles to the API Administration Database
The EdFi_Admin database stores the data required to manage API keys and secrets, as well as Education Organization and Profile assignments. When the API is initialized, the names of the Profiles that have been configured into the API will be published to the Profiles table. This process performs a one-way publishing and will not remove existing Profile names that are no longer contained within the API configuration.
The EdFi_Admin tables related to this process are shown below.