Tutorial 02 04 Configuring Self Hosting

Configuring Self-Hosting

To run an instance of your web service, you'll need to generate a "self-hosting" application.

The term "self-hosting" refers to the fact that in .NET Core environments, web applications are typically hosted within a custom application that you write. In most cases, this will be a simple console application. Even if you ultimately plan to host your services in a web server such as Internet Information Server (IIS), you will still need to generate a self-hosting application, which will be hosted and managed by IIS.

Of course, you are not expected to implement the functionality of a web server yourself. That functionality is provided by the ASP.NET Core environment in the form of a web server called Kestrel. You simply write an application that uses Kestrel to host an instance of your web site and/or services.

The Harmony Core solution templates provide a project for creating a self-hosting console application. The project is called Services.Host, but by default it doesn't contain any code. This is because the code that will be needed in the self-hosting application will depend on the types of endpoints and other options that you select in the Harmony Core CLI tool. Several options cause additional code to be generated into the self-hosting program.

Generating a Self-Hosting Program

In the previous tutorial (Enabling OData Support), we opted to generate self-hosting code by selecting ODataGenerator as one of the Enabled generators for each included structure. And when we subsequently generated code, CodeGen created the source files for this. In this tutorial, we'll add those files to the project, but first we need to set up some data for the service to work with.

Generating Harmony Core Sample Data

In addition to generating a self-hosting application, if you are working with the Harmony Core sample data, you will need to generate additional code that causes the sample data files to be created and loaded each time your application starts, and deleted when your application stops.

This mechanism is designed to ensure that you will have consistent test data each time you start the service, which can be especially important if you intend to incorporate unit testing within your environment.

This functionality is unlocked by selecting another option:

1. At a Windows prompt, move to the directory with your Harmony Core solution, and type harmonycore gui. When the GUI for the Harmony Core CLI tool opens, go to the OData screen, scroll down to the Enable test file creation option, and double-click it.

2. In the "Enter new value" screen, click the diamond icon to the right of Enable test file creation. (The diamond will change to a checkmark.) Then click OK.

VERY IMPORTANT: Do not select this option unless you are working with the Harmony Core sample data and wish to create and delete your data files each time your services start and stop. If you enable this option in a production environment, IT WILL CAUSE YOUR DATA FILES TO BE DELETED!

Generating Custom Sample Data

Skip this section if you are working through the Building a Service from Scratch tutorial.

If you are working with your own repository and data files, it is still possible to use the auto-create/auto-delete mechanism to create your own data files as the service starts and ends. To do this,

3. Provide a sequential file containing the data to be loaded. The file must be in the same location and have the same file name as the actual data file, but with a .txt file extension.

4. Provide an XDL file for the data file, again in the same location and with the same name, but with a file extension of .xdl.

Setting Logical Names for Data File Access

Skip this section if you are working through the Building a Service from Scratch tutorial.

By default, the generated self-hosting code detects any logical names that are used to access your data files (based on the file specifications present in your repository) and sets those logical names to point to the included SampleData folder each time your service starts. This means that the easiest way to get up and running with your own data is to drop a copy of your data files into the SampleData folder.

In most cases, however, you will likely want to access your data files from their current location in your environment. To do so you will need to do two things:

• Prevent the self-hosting code from setting environment variables during service startup
• Provide values for the environment variables in different way

Preventing Startup from Setting Environment Variables

Skip this section if you are working through the Building a Service from Scratch tutorial.

5. To prevent the startup code from setting data access environment variables to point to the SampleData folder, enable the Disable file logicals option on the OData screen in the Harmony Core CLI tool. (Double-click this option on the OData screen, click the diamond icon to the right of Disable file logicals to change the diamond into a checkmark, and then click OK.)

Customizing Environment Variables

Skip this section if you are working through the Building a Service from Scratch tutorial.

If you suppress automatic environment variable setting, you will need to ensure that your services are able to access your data files by setting those environment variables in some other way. Exactly how to do this depends on your exact requirements. You will find several options by reviewing the following:

• Environment Variables
• Custom File Specs
• Multi-Tenancy

Generating the Updated Code

6. Save the settings you made by selecting File > Save from the menu.

7. Regenerate generated code for your solution by selecting Codegen > Regen from the menu.

When code generation is finished, a message will list the files that were generated:

Adding the Self-Hosting Code to the Services.Host project

The next step is to add the generated self-hosting source files to the Visual Studio project:

8. In Visual Studio Solution Explorer, right-click on the Services.Host project and select Add > Existing Item.

9. Select the two new source files (SelfHost.dbl and SelfHostEnvironment.dbl) and click the Add button.

Building the Code

The entire solution should now be in a buildable and runnable state, although your web service does not have any usable endpoints yet!

10. Build the project by selecting Build > Rebuild Solution from the Visual Studio menu.

11. Check the Output window. You should see something like this:

    Rebuild started...
    Restored C:\hc\tut\MyApi\Services.Controllers\Services.Controllers.synproj (in 151 ms).
    Restored C:\hc\tut\MyApi\Services.Models\Services.Models.synproj (in 142 ms).
    Restored C:\hc\tut\MyApi\Services\Services.synproj (in 156 ms).
    Restored C:\hc\tut\MyApi\Services.Isolated\Services.Isolated.synproj (in 152 ms).
    Restored C:\hc\tut\MyApi\Services.Host\Services.Host.synproj (in 246 ms).
    1>------ Rebuild All started: Project: Repository, Configuration: Debug Any CPU ------
    2>------ Rebuild All started: Project: Services.Models, Configuration: Debug Any CPU ------
    3>------ Rebuild All started: Project: Services.Controllers, Configuration: Debug Any CPU ------
    4>------ Rebuild All started: Project: Services.Isolated, Configuration: Debug Any CPU ------    
    5>------ Rebuild All started: Project: Services, Configuration: Debug Any CPU ------
    6>------ Rebuild All started: Project: Services.Host, Configuration: Debug Any CPU ------
    ========== Rebuild All: 6 succeeded, 0 failed, 0 skipped ==========
    ========== Elapsed 00:47.460 ==========
    

Running the Code

12. In Visual Studio Solution Explorer, right-click on the Services.Host project, and then select Set as Startup Project from the context menu.

The name of the project file should now be displayed in bold in Solution Explorer.

13. Press F5 (Start Debugging) to start the self-hosting application.

You should see a console window appear with text like this:

Hosting environment: Development
Content root path: D:\MyApi\Services.Host\bin\Debug\net6.0\
Now listening on: http://localhost:8085
Now listening on: https://localhost:8086
Application started. Press Ctrl+C to shut down.

14. Look in the SampleData folder for the project. You should find that five ISAM files have been created and loaded with data. These data files will be deleted when the hosting program closes.

Interacting with the Service

Your web service currently has very limited functionality because you have not yet enabled the options to create data-centric endpoints. But there is some functionality present. Your service should currently expose the following:

• An OData service document that lists the OData entities that the service knows about
• An OData metadata document that defines the operations and data types exposed by the service
• API documentation based on Swagger UI, although your service currently has no endpoints to document!

Viewing the Service Home Page

Solutions based on the harmonycore template include a static HTML home page that includes links to the resources.

15. Open a web browser and go to the URL https://localhost:8086. You should see a page that looks like this:

Viewing the OData Service Document

16. Click on the OData Entities link.

You should see something like this:

This lists the data types that the service knows about. But we haven't yet implemented any operations for any of those types, so the information is not currently useful to us.

If you see something that looks more like the following, it's the same thing, but your browser doesn't know how to format JSON data.

{"@odata.context":"https://localhost:8086/odata/v1/$metadata","value":[{"name":"Customers","kind":"EntitySet","url":"Customers"},{"name":"Items","kind":"EntitySet","url":"Items"},{"name":"Orders","kind":"EntitySet","url":"Orders"},{"name":"OrderItems","kind":"EntitySet","url":"OrderItems"},{"name":"Vendors","kind":"EntitySet","url":"Vendors"}]}

If your browser supports extensions, check its app store for an extension that formats JSON data.

Viewing the OData Metadata Document

17. Click on the OData Metadata (XML) link.

You should see something like this:

This XML document currently defines the data types that are going to be exposed by the service. But again, there is no information about service endpoints because none have been created yet.

Viewing the API Documentation

18. Click on the API Documentation link.

You should see the API documentation home page, which looks something like this:

Notice that this lists metadata and schemas, but no operations for endpoints. This is because the API documentation for Harmony Core services is generated at runtime based on the web service endpoints exposed by the service, and this service does not currently expose any endpoints.

You will learn more about API Documentation once you have added some useful endpoints to your web service.

Stop the Service

19. Switch focus to the console window of the self-hosting application and press Ctrl+C.

20. Check the SampleData folder. You should find that the five ISAM files have been deleted.

---

Next topic: Entity Collection Endpoints

---