Tutorial 1 - Building an API

Step 1 - (Both Code First and Database First)

1. Open Microsoft Visual Studio 2019 or 2023.

2. Click on the main menu bar at the top of the screen and select View.

3. Click on Other Windows.

4. Navigate to the flyout menu and select Example AI - xAI.

Step 2

The xAI Tool window will appear as shown below.

Step 3

1. Click on the Help Tab.

2. Select the Dot Net Version (5,6, or 7)

3. We are building an API. Click on the icon next to the API line to copy the GitHub location to the clipboard.

Step 4

1. Click on the File menu at the top of the screen.

2. Select Clone Project

3. (We will clone an 'empty' project from the Example AI GitHub repository. This eliminates most manual setup steps when creating a project.)

Step 5

1. The following Visual Studio screen will appear.

2. Paste the text you copied to the clipboard into the Repository location box.

3. Provide a path to the project. This may be anywhere you choose to set the location to.

4. Click the Clone button.

5.This will clone the project into the location you specified.

6.The GitHub manager window may appear. You can dismiss this window. (Click the X on the top right of the border to close it.)

Step 6

1. Once Visual Studio has finished loading the project, click on the solution filename (apicore5sln.sln) to open the solution. (In xAI we work with solutions and not individual products. Solutions contain multiple projects, including test projects.)

Step 7 = (Code First only - Skip to step 9 if using Database First)

1. If the example AI window has collapsed, click on the side bar Tab to expand it.

2. If not selected, click on the Code First Tab to begin a Code First project.

3. To skip the step of typing in the Table Names and field names, you can click on the Load Sample button. The grid will fill with all the information needed to generate a Code First solution.

4. Alternatively, you can type in the necessary information or load from a csv file that has been prepared previously. (A video with instructions on using the Code First Tab is available in the video library.)

5. Click the Generate button to create the classes. After a short delay, an alert box will pop up when the classes have been generated.

Step 8

1. Once the classes have been generated, the next step is to change the default database name in the appsettings.json

2. By default, it's xaidemo. (The name comes from the GitHub image).

3. You may want to change it but that's only necessary if you have an existing database named xaidemo on your server.

4. For this example, we change it to codefirst.

5. The next step is to select Tools -> NuGet Package Manager -> Package Manager Console.

6. We now do our first database migration by typing in add-migration initial.

7. The system will build the project and, in a moment, or so you will get a message indicating:

Build started... followed by

Build succeeded.

8. Finally, you enter - Update database and press the return button. After a short pause the database will be created, and all tables and keys set.

Note: If you want to keep the database migration paths intact, you can use SQL Server Management Studio to add, edit or delete records but don't use it to make changes to the schema. Otherwise, you will lose the Entity Framework capability to reverse migrations.

Just make schema changes in the Code First Tab and/or the underlying classes in the Models directory of the application.

Here, we pick up as if this was a Database First Project.

Step 9a - (Code First specific instructions.)

1. Click on the SQL Tab.

The image below shows the SQL Tab screen.

2. The connection string field is pre-populated (It's set in the Default Tab).

3. The setting is appropriate for most situations where you have a local database installed on your machine. If you need to connect to a remote server, you can consult your database support team for the exact connection string.

4. Press the Connect button.

5. The dropdown next to the Connect button will fill with the names of the databases on your machine.

6. Click on the database name called codefirst.

Step 9b - (Database First specific instructions.)

1. Click on the SQL Tab.

The image below shows the SQL Tab screen.

2. The connection string field is pre-populated (It's set in the Default Tab).

3. The setting is appropriate for most situations where you have a local database installed on your machine. If you need to connect to a remote server, you can consult your database support team for the exact connection string.

4. Press the Connect button.

5. The dropdown next to the Connect button will fill with the names of the databases on your machine.

6. Click on the database name called codefirst.

Step 10

1. In this example we have unchecked the guest schema (nothing is in this database schema anyways), and we have unchecked the EFMigrations table. Nothing prevents us from building using the EFMigrations table, we are just demonstrating that you can freely choose the tables you wish to include in your solution.

Step 11

1. Click on the Actions Tab. The API pipeline will be pre-selected. (The pipeline in a series of steps that are executed one after another in the order of the pipeline elements.)

2. Click on the Select All / Deselect All button. All the elements in the pipeline will be selected.

3. Click on the Execute button to perform all the selected actions in the pipeline.

4. Before going ahead, you will be prompted with if you wish to proceed. The banner at the top of the dialog tells you how many tables have been selected as a precaution in case you don�t wish to include so many tables in the project.

5. Choose Yes to procced.

Step 12

1. The program will go ahead and perform all the tasks in the pipeline. A dialog box with progress bar will provide detailed information as the program proceeds. (This information is also logged to the debug window).

2. In most cases, it should take less than a minute to build the API project.

3. Once the program has completed, an All Done! message box will pop up.

4. Click OK to dismiss the dialog.

Step 13a - Code First specific instructions)

1. Build and run the project (Click Debug, Start Debugging or F5, or Debug, Start without Debugging (Shift F5)

2. Depending upon the number of tables and the complexity of the project, building may take a few minutes (generally quite a bit longer than the generation time).

3. The Swagger main screen will appear as shown below.

4. You may try out all the actions using Swagger but you will need to add data since no data is present in the database yet. (There are plenty of examples on the web and YouTube on how to use swagger if you are unfamiliar with it.)

Step 13b - Database First specific instructions)

1. Build and run the project (Click Debug, Start Debugging or F5, or Debug, Start without Debugging (Shift F5)

2. Depending upon the number of tables and the complexity of the project, building may take a few minutes (generally quite a bit longer than the generation time).

3. The Swagger main screen will appear as shown below.

5. You may try out all the actions using Swagger. In this case we have generated the data from a script so all data is already present unlike the Code First approach where we have a database but no data yet.

Note: There are plenty of examples on the web and YouTube on how to use swagger if you are unfamiliar with it.

Step 14

1 We have also generated all the tests using x-Unit for the API. (The x-Unit references came with the project clone operation from GitHub). You can now click on View and then select the Test Explorer. After running all the tests, you will see the success status of the running all the tests.

2. Depending upon the number of tables and the size of the project, it may take a few minutes to run all the tests. You should expect them to all run successfully as shown below.

Note: You can go ahead and run all the tests before adding or changing data to the database. Since we are testing the controllers and not SQL Server or Entity Framework itself, we mock the data using the Entity Framework in Memory database.

Step 15

1. At this point you have successfully generated the API but may now do a little 'fine-tuning'.

2. Skip over the Examples Tab and select the Order Tab.

By default, xAI will automatically sort the output of the API calls based upon the values set in the default settings.

This default is a single sort order, typically ID ascending or first Alpha Field ascending which is the first alpha/character field in the table ordinal order.

However, if the default isn't enough, you may select from up to 6 sort orders with a mix of ascending order and descending order.

For example, in the screen below, we are sorting the lists of the Order Header by the Order Date field, Order Status field, Full Name field, Transaction Id field and then the Final Order Total field Descending.

3. Select the Order table in the Order dropdown.

4. Select the order sequence in the boxes as shown.

5. Click on the Execute button, and in just a second or two, the system will replace the order criteria according to the selections made.

Step 16

1. Click on the Include Tab.

2. By default, xAI does not include any subsidiary joins. However, you may wish to include various related tables so that the elements may be included with the API call.

3. Below, you can see that when the order table is selected here, the system reports that the following tables have foreign keys to the order table and may be included by clicking on the checkbox to select them.

4. Then hit the Execute button.

1. Click on the Where Tab This tab will allow you to change the selection criteria for the records.

2. Select the table from the table dropdown.

3. Then, select the field from the When 1 dropdown.

4.Enter the criterion in the Expression box.

5. Note: The criterion is basically the >= expression without the brackets. The examples on the form show the correct syntax to use.

6. Click on the Execute button to change the Where clause for the table.

7. This takes just a second or so and will make the change to the database select logic.

Note:This is embedded in the code and should be thought of as a global selection filter.

This allows the user to select which fields to put in results and accepts and in what order.

3. Additionally, there are specific values for masks and field formatting.

4. Click on the Execute button once you have made your selections.

You have now completed the API tutorial.

The remaining tabs don't apply to API applications.

(A video with instructions on using the Fields Tab is available in the video library.