Tutorial 02 04 Configuring Self Hosting
To run an instance of your web service you will 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 also 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, and that application will in-turn 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 already 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 by configuring the various options in the regen batch file. Several options cause additional code to be generated into the self-hosting program.
To generate the required self-hosting code into the Services.Host project you must enable an option in the regen batch file.
-
Edit regen.bat and scroll down to the section where all the code generation options are defined.
-
Locate and remove the comment from the
ENABLE_SELF_HOST_GENERATIONoption, like this:set ENABLE_SELF_HOST_GENERATION=YES
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 enabling another option:
-
Locate and remove the comment from the
ENABLE_CREATE_TEST_FILESoption, like this:set ENABLE_CREATE_TEST_FILES=-define ENABLE_CREATE_TEST_FILES
VERY IMPORTANT: Do not enable 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!
Skip this section if you are working through the Creating a Basic Solution tutorial.
If you are working with your own repository and data files then 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 you must:
-
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
.txtfile extension. -
Provide an XDL file for the data file, again in the same location, with the same name, but with a file extension of
.xdl.
Skip this section if you are working through the Creating a Basic Solution 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 are likely to 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 appropriate values for the environment variables another way.
Skip this section if you are working through the Creating a Basic Solution tutorial.
-
To prevent the startup code setting data access environment variables to point to the SampleData folder, enable the
DO_NOT_SET_FILE_LOGICALSoption, like this:set DO_NOT_SET_FILE_LOGICALS=-define DO_NOT_SET_FILE_LOGICALS
Skip this section if you are working through the Creating a Basic Solution tutorial.
If you suppress the automatic setting of environment variables then you will need to ensure that your services are able to access your data files, by causing those environment variables to be set some other way. Exactly how to do this depends on your exact requirements. You will find several options by reviewing:
-
Save your changes to the regen.bat file.
-
If you don't already have a command prompt open in the solution folder, use the
Tools > Command Prompt (x64)menu option to open a Windows command prompt, and type the following command:cd .. -
Type the following command to regenerate your code:
regen
As the batch file executes you will see various messages confirming which source files are being generated. Look for the word DONE to indicate that all code generation tasks completed successfully.
Enabling the 'ENABLE_SELF_HOST_GENERATION' option causes two additional source files to be generated into the Services.Host folder:
Services.Host\SelfHost.dbl
Services.Host\SelfHostEnvironment.dbl
The next step is to add the new source files that were just generated to the Visual Studio project:
-
Right-click on the
Services.Hostproject and selectAdd > Existing Item. -
Select the two new source files and click the
Addbutton.
The entire solution should now be in a buildable and runnable state, although your web service does not have any usable endpoints yet!
-
Build the project by selecting
Build > Rebuild Solutionfrom the Visual Studio menu. -
Check the
Outputwindow, you should see something like this: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 ==========
- In Visual Studio Solution Explorer, right-click on the
Services.Hostproject then selectSet as Startup Project.
The name of the project file should now be displayed in bold.
- Press
F5(start debugging) to start the self-hosting application.
You should see a console window appear with text similar to this:
Hosting environment: Development
Content root path: D:\MyApi\Services.Host\bin\Debug\netcoreapp3.1\
Now listening on: http://localhost:8085
Now listening on: https://localhost:8086
Application started. Press Ctrl+C to shut down.
- Look in the
SampleDatafolder, you should find that the five ISAM files have been created and loaded with data. These data files will be deleted again when the hosting program closes.
Your web service currently has very limited functionality, because you have not yet enabled the options to create any data-centric endpoints. But there is SOME functionality present. Your service should currently expose:
- 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!
Solutions based on the harmonycore template include a static HTML home page that includes links to the resources.
- Open a web browser and go to the URL
https://localhost:8086.
You should see that page, which looks like this:
- Click on the OData Service Document link.
You should see something like this:
This document 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 this:
{"@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"}]}
It's the same thing, but your browser doesn't know how to format JSON data. If your browser supports extensions, check its app store for an extension that formats JSON data.
- Click on the OData Metadata Document 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 not yet any information about service endpoints because none have been created yet.
- Click on the API Documentation link.
You should see the API documentation home page that looks something like this:
Notice the text No operations defined in spec! 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 your 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.
-
Either switch focus back to Visual Studio and type
Shift + F5(stop debugging), or switch focus to the console window of the self-hosting application and typeCtrl + C. -
Check the
SampleDatafolder, you should find that the five ISAM files have been deleted.
Next topic: Entity Collection Endpoints