Development on Windows/.NET

First please refer to the Basic Concepts and Architecture pages to understand the philosophy, concepts and architecture of Thriot.

The GitHub Url of Thriot is here:  https://github.com/kpocza/thriot

This tutorial is expecting the v0.6 version release of the source code.

You can clone, download, fork, branch it or you can do with the source code anything you want according to the MIT licence agreement.

Development environment requirements

  • Visual Studio 2015
  • Azure SDK v2.6 with Storage emulator AND/OR
  • Microsoft SQL Server 2012 – Express edition (at least) OR
  • PostgreSql 9.4 AND/OR
  • Cassandra 2.1 (for telemetry only) AND/OR
  • Azure EventHub (for queue only)

Steps to build the development environment

To ensure high quality and regression-free code, Thriot has a many-many unit and integration tests. While working in Visual Studio your friends are the unit/integration tests which can be configured by setting specific run settings while the website settings are not affected when starting them from VS. The websites are configured to use IIS Express and local Azure emulator.

If you don’t specify test runsettings then everything is mocked and/or uses some kind of in-memory data storage. So first do the following steps:

  • Open Service\Thriot.Service.sln using Visual Studio
  • Do a full build
  • Run all unit tests. Correct any issues until every test turns green. There should not be any issues.

test1

 

Specializing your environment

You can turn most of your unit tests to integration tests by changing the runsettings.  The general rule is that the runsettingsnot only influences the runtime environment for the test projects but it tells what storage environment to use (Azure development storage, MS SQL or PostgreSql, etc).

You can either create a local Azure, SQL Express or PostgreSql based runsettings. It depends on your needs.

To select a test runsetting it’s important to first open the Test Explorer bar which will enable the required menu items. In The TEST/Test Settings/Select Test Settings File menu select one of the following test settings from the TestRunSettings folder:

  • AllInMemory.runsettings – everything is mocked
  •  AllAzure.runsettings  – Storage is Azure based, messaging is SQL-based
  • AllSql.runsettings  – Everything is SQL-based
  • AllPgSql.runsettings – Everything is PostgreSQL-based
  • PgSqlCassandraTelemetry.runsettings – Management and Messaging is stored in PostgreSQL, Telemetry is stored in Cassandra
  • etc

Since in Azure and SQL mode the messaging service is Sql based in unit/integration tests then these are the common steps for Azure and Sql configurations (not needed for other configuration, eg. PgSql):

  • Open Service\Thriot.Service.sln using Visual Studio
  • Install Microsoft SQL 2012 Express (at least)
  • Create ThriotMessaging database in the .\SQLEXPRESS instance (note: this is mandatory for Azure developers also)
  • Run Service\Messaging\Scripts\Sql\CreateDB.sql on the ThriotMessaging database
  • Create c:\Thriot\log folder. Ensure that the current user has write permission to this folder
  • Ensure that all webapi  (Thriot.{Management, Messaging, Platform, Reporting}.WebApi) and the website (Thriot.Web) project are set to startup projects. This will ensure that when pressing F5 all websites will start in IIS Express.
startupproj

Further steps to create local Azure development environment

  • Do a full build
  • Select the AllAzure.runsettings  testsettig file from the Test Settings menu
  • Install Azure SDK along with the Storage emulator and ensure that it’s started
  • Run Service\Misc\Thriot.CreateAzureStorage\bin\Debug\Thriot.CreateAzureStorage.exe to create the necessary tables in the Azure Table Storage emulator
  • Run all unit (integration) tests. Correct any environment issues until every test turns green
  • Hit F5. The management website should load in your browser at http://localhost:7999
  • Try registering a new user and play with the website
  • Start Service\Platform\Thriot.Platform.WebsocketService\bin\DevAzure\Thriot.Platform.WebsocketService.exe from command line.
  • Open Client\DotNet\Thriot.Client.DotNet.sln in an other Visual Studio instance
  • Do a full Debug build
  • Select TestRunSettings\IISExpressDevAzure.runsettings in Test/Test Settings/Select Test Settings file menu option.
  • For subsequent builds if you changed the Url Settings discussed in the “Explaining Settings …” section ensure that the settings are that you can see in the picture below
  • Run all integration tests (ensure that the website is still running in IIS Express). Correct any environment issues until every test turns green.

integtestsucc

Further steps to create local SQL Express-based development environment

  • Do a full rebuild
  • Open the AllSql.runsettings  test settings file from the Test Settings menu
  • Create two databases in the .\SQLEXPRESS instance: Thriot, ThriotTelemetry
  • Copy and change if necessary the Service\Misc\Thriot.CreateSqlStorage\Thriot.CreateSqlStorage.exe.Sql.config file to Service\Misc\Thriot.CreateSqlStorage\bin\Debug\Thriot.CreateSqlStorage.exe.config
  • Run Service\Misc\Thriot.CreateSqlStorage\bin\Debug\Thriot.CreateSqlStorage.exe to create the necessary tables in Thriot database in the local SQL Express 2014
  • Run all unit (integration) tests. Correct any environment issues until every test turns green
  • To do integration tests from the client side in this mode please refer the page that describes SQL-based Test environment creation steps in Test Environment

Steps to create local PostgreSQL-based development environment

  • Install PostgreSql 9.4
  • Create the following users (aka login roles) thriot, thriotmessaging, thriottelemetry with the same passwords as the usernames. Use Pgadmin III.
  • Create the following databases Thriot, ThriotMessaging, ThriotTelemetry, set the previously created users as owners for these Dbs, respectively
  • Do a full rebuild
  • Open the AllPgSql.runsettings  test settings file from the Test Settings menu
  • Copy and change if necessary the Service\Misc\Thriot.CreateSqlStorage\Thriot.CreateSqlStorage.exe.PgSql.config file to Service\Misc\Thriot.CreateSqlStorage\bin\Debug\Thriot.CreateSqlStorage.exe.config
  • Execute Service\Misc\Thriot.CreateSqlStorage\bin\PgSql\Thriot.CreateSqlStorage.exe
  • Login as thriotmessaging user to PostgreSql and run the Service\Messaging\Scripts\PgSql\CreateDB.sql script against the ThriotMessaging database
  • Run all unit (integration) tests. Correct any environment issues until every test turns green
  • To do integration tests for the client side in this mode please refer the page that describes PostgreSql-based Test environment creation steps in Test Environment

Steps to create PostgreSQL + Cassandra 2.1-based development environment

  • In this case the Management database and the messaging storage is PostgreSQL based while the telemetry data is stored in Cassandra
  • Install PostreSql 9.4
  • Install Cassandra 2.1 (https://www.digitalocean.com/community/tutorials/how-to-install-cassandra-and-run-a-single-node-cluster-on-a-ubuntu-vps). Replace with Java 1.8 and Cassandra 2.1
  • Create the following users (aka login roles) thriot, thriotmessaging with the same passwords as the usernames. Use Pgadmin III.
  • Create the following databases Thriot, ThriotMessaging, set the previously created users as owners for these Dbs, respectively
  • Do a full rebuild
  • Open the PgSqlCassandraTelemetry.runsettings  test settings file from the Test Settings menu
  • Copy and change if necessary the Service\Misc\Thriot.CreateSqlStorage\Thriot.CreateSqlStorage.exe.PgSql.config file to Service\Misc\Thriot.CreateSqlStorage\bin\Debug\Thriot.CreateSqlStorage.exe.config
  • Execute Service\Misc\Thriot.CreateSqlStorage\bin\PgSql\Thriot.CreateSqlStorage.exe
  • Login as thriotmessaging user to PostgreSql and run the Service\Messaging\Scripts\PgSql\CreateDB.sql script against the ThriotMessaging database
  • The Cassandra telemetry settings are the following:
    • Single node called ubuntucas1
    • Keyspace name: test
  • You need to ensure that a Cassandra installation is available with the above parameters
  • Run all unit (integration) tests. Correct any environment issues until every test turns green
  • To do integration tests for the client side in this mode please refer the page that describes PostgreSql-based Test environment creation steps in Test Environment

Explaining Settings for the Development environment

The following explanation is based on the local azure development environment. Other environments have similar configuration settings with similar meanings. It’s you task to adopt these settings to your chosen environment.

In the default configuration Thriot’s Management Connection (the database that storage structural data and configuration) points to the Azure Storage Emulator’s Development Table Storage.

{
    "ConnectionString": {
        "ManagementConnection": {
            "ConnectionString": "UseDevelopmentStorage=true",
            "ProviderName": ""
        }
    }
}

The messaging service has this configuration settings besides the Messaging DB connection:

{
    "ConnectionString": {
        "MessagingConnection": "Server=.\\SQLEXPRESS;Database=ThriotMessaging;Trusted_Connection=True;"
    }
}

After running Thriot.CreateAzureStorage.exe described above the following configuration settings will be entered into the Settings table in the Azure Development Storage.

azuredev

 

The configuration settings are created by default to support the development environment.

The following table explains the configuration settings:

Category ConfigKey Explanation
Connection TelemetryConnection Telemetry connection string for Azure Table Storage, MSSQL, PostgreSql, Cassandra, etc based Telemetry data stores
Microservice MessagingServiceApiKey API key to access the messaging service. This API key is a crypto-random number that is unique for every installation
Microservice MessagingServiceEndpoint Messaging service endpoint Url
Microservice TelemetrySetupServiceApiKey Telemetry setup service API Key. The same applies as for the MessagingServiceApiKey.
Microservice TelemetrySetupServiceEndpoint Telemetry service endpoint Url
PublicUrl ManagementApiUrl Public Url address for the Management API
PublicUrl PlatformApiUrl Public Url address for the Platform API
PublicUrl PlatformWsUrl Public Url for the Platform Websocket interface
PublicUrl ReportingApiUrl Public Url for the Reporting API
PublicUrl WebsiteUrl Public Url for the Central management website
Runtime EmailActivation Boolean value indicating whether email activation is required for new registration or not.In development and test environment this value should be false. Please set the value to true in Production environment.
Runtime ServiceProfile The service profile value that can be ServiceProvider, SingleCompany or SingleService.By default ServiceProvider is used to provide the most freedom in development time.
Version Database Database version. Subsequent executions to the storage creator application will consider this version number and execute upgrade steps higher than this version.

As mentioned before the Central Management website uses the Management API and the Platform API so that it’s necessary to specify the API urls for the website. Since this website is a client-side heavy solution completely decoupled from the business logic the API url settings are also specified in JavaScript. The default configuration settings are the following (Thriot.Web/config/siteRoots.js):

app.constant('siteRoots', {
    managementRoot: 'http://localhost:8000/api/v1',
    reportingRoot: 'http://localhost:8002/rapi/v1'
});

 

Upgrading

To upgrade to a newer/newest version do the following steps:

  1. Get the latest source snapshot
  2. Do a full rebuild
  3. Execute the Management  storage creator applications (CreateAzureStorage or CreateSqlStorage) which won’t delete any data just upgrade the DB schema
  4. For the Messaging storage execute the appropriate CreateDB.sql script for Sql or PgSql targets
  5. Execute all unit/integration tests
Advertisements