This section outlines how to use code generation to create an Ed-Fi ODS / API Client SDK using a Windows environment targeting C#. The high-level steps are:
Each step is outlined in detail below.
Step 1. Install Latest Version of Java
If you don't already have Java installed, navigate to https://java.com/en/download/ and download the latest installer. Run the installer to install the latest version of Java. In case you're wondering: the code generation leverages Java, but it does output C# code.
Step 2. Download the Swagger Codegen JAR File
Download the latest version of the Swagger Codegen JAR 2.3.0+. Windows users can use Invoke-WebRequest in PowerShell 3.0+.
For more information and download options visit https://github.com/swagger-api/swagger-codegen.
When generating an SDK using the Swagger CodeGen resources in a language other than C# or Java and there are profiles defined in the OpenAPI specification file, be sure to verify that the proper contentTypes where created during the code generation.
Step 3. Generate the SDK Source Files
The SDK source files are generated using swagger metadata via a few simple PowerShell commands. You can see the available metadata endpoints for SDK generation at https://api.ed-fi.org/v3.4.0/api/metadata?sdk=true.
A detailed description of the switch options can be found at https://github.com/swagger-api/swagger-codegen.
To generate SDK source files, navigate to the folder containing swagger-codegen-cli.jar and run the following commands in PowerShell 3.0+ to generate C# SDK source files.
Alternatively you can use unified SDK generation endpoints that combine resources, descriptors and extensions under one namespace/directory in the generated SDK:
Wait for the Swagger Codegen to finish generating code. A Visual Studio Solution named EdFi.OdsApi.Sdk.sln will be created with the SDK artifacts.
Step 4. Use the SDK in a Sample C# Program
- Open EdFi.OdsApi.Sdk.sln in Visual Studio.
- Right-click on the solution and click Restore NuGetPackages.
- Make sure Copy Local is set to true for the RestSharp reference.
- Build the solution.
- Right-click on the solution and add a new project. Choose the type Visual C# > Console Application. Name the project EdFi.OdsApi.SdkClient.
Right-click on Edfi.odsApi.SdkClient > Set as Startup Project.
In Solution Explorer, right-click EdFi.OdsApi.SdkClient project references node and click Add Reference.
In the Add Reference > Projects tab select EdFi.OdsApi.Sdk, and then click OK.
- Use the Package Manager Console to install the RestSharp and Newtonsoft libraries. At the
install-package restsharp -version 105.1.0 -project EdFi.odsApi.SdkClientand
install-package Newtonsoft.Json -project EdFi.odsApi.SdkClient.
Open the Program.cs file and add the following
usingstatements at the top of the file:
Edit the Program.cs file and paste the following into the
Mainmethod. The client and key are using a publicly available sandbox environment with sample data hosted by the Ed-Fi Alliance.
Add a .cs file named TokenRetriever.cs and copy the following code to help with OAuth integration.
- Build the project and run it without debugging (Ctrl+F5) and you should see the following results:
With that, you're done!
This exercise leveraged a publicly available instance of the API, which contains the surface for a core implementation. If you're working with a specific platform host, a great next step is to use these same techniques to generate an SDK for that platform. If the platform host has extended the data model, your new code will automatically include those structures in the data access components in the generated code.