Tutorial 02 04 Configuring Self Hosting
To run an instance of your web service, you 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, 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 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 GUI tool. Several options cause additional code to be generated into the self-hosting program.
In the previous tutorial (Enabling OData Support), we instructed code generation to generate self-hosting code when we selected ODataGenerator as one of the "Enabled generators" for each included structure. And when we subsequently generated code by selecting Codegen > Regen from the menu, 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.
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:
-
In the Harmony Core GUI tool, go to the OData tab and scroll down to the "Enable test file creation" option. Double-click that option and in the "Enter new value" screen, click the diamond icon to the right of "Enable test file creation". (The diamond icon will change to a checkmark.) Then click OK.
-
Save the "Enable test file creation" setting by selecting File > Save from the menu.
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 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,
-
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 and with the same name, but with a file extension of
.xdl.
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 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 in different way
Skip this section if you are working through the Building a Service from Scratch tutorial.
- 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 tab of the Harmony Core GUI tool. (Scroll down to the option, double-click it, and click the diamond icon to the right of "Disable file logicals" to turn the diamond into a checkmark. Then click OK.)
Skip this section if you are working through the Building a Service from Scratch tutorial.
If you suppress the automatic setting of environment variables, 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 the settings you made by selecting File > Save from the menu of the Harmony Core GUI tool.
-
Then regenerate generated code for your solution by selecting Codegen > Regen from the menu.
When CodeGen is finished generating code, a message will be displayed listing the files that were generated:
The next step is to add the source files that have been generated to the Visual Studio project:
-
Right-click on the
Services.Hostproject and selectAdd > Existing Item. -
Select the two new source files (SelfHost.dbl and SelfHostEnvironment.dbl) 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:Rebuild started... Restored C:\hc\tutorial2\MyApi\Services.Models\Services.Models.synproj (in 133 ms). Restored C:\hc\tutorial2\MyApi\Services.Controllers\Services.Controllers.synproj (in 133 ms). Restored C:\hc\tutorial2\MyApi\Services.Isolated\Services.Isolated.synproj (in 134 ms). Restored C:\hc\tutorial2\MyApi\Services\Services.synproj (in 145 ms). Restored C:\hc\tutorial2\MyApi\Services.Host\Services.Host.synproj (in 211 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 ==========
- 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 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.
- Look in the
SampleDatafolder. 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.
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 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!
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 a page that looks like this:
- 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 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 (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 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, 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.
-
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