devonfw guide

This is the fastest and most efficient way. You will be installing and starting a project thanks to the template available in the NuGet Gallery using CLI. For this part you will need to have .NET 6.0 SDK installed. You can run the following command to check your version:

If you don’t get any response please follow the installation guide provided by Microsoft to install the latest version of .Net SDK for your OS.

This method is a little more time consuming, but it allows for a more customized configuration and project structure. You will be using Visual Studio 2022 to create the project and add everything you need by hand.

If you try to execute the devon4net template on macOS or an earlier version of Windows, such as Windows 7, you will receive the following error message:

Because these operating systems lack ALPN(Application-Layer Protocol Negotiation) functionality, Kestrel does not handle HTTP/2 with TLS.

To resolve this, navigate to 'appsettings.json' and change the Kestrel configuration as seen below:

Here are some interesting references to continue learning about this topic:

In order to create our own certificate for development purposes we will be using OpenSSL toolkit. To ensure correct behavior, make sure the tool is properly installed.

To run commands for OpenSSL, you will need to add OpenSSL to your environment, variables, or open a OpenSSL command prompt.

Once you have created a certificate or in case you already have yours, you can add it to your project thanks to devon4net tools.

Here are some interesting references to continue learning about this topic:

We can configure it to work either with a secret key or a certificate.

If you choose certificate, you will need to add a certificate to your project, and specify the password and the encryptionAlgorithm used. You can learn how to do it following the tutorial included in this document.

If you specify both, the secret key will take priority.

For example lets specify the next:

This would create the following configuration:

Json Web Tokens work with claims. A Claim is a piece of information about a subject. It is similar to a key-value pair, where the value will be the claim type, such as the name or the role of an authenticated user. This claims are stored inside a JSON and then encrypted forming the JWT.

In .Net we can create Claims using the Claim class avaiable in System.Security.Claims. It has many constructors but the most important is the following one, where you can create a Claim based on two strings.

You can choose between a variety of claim types thanks to the ClaimType class. As you can see in the previous piece of code, in this case we have asserted a name and a role in two claims. This could be for a user, for example.

In JWT component we have a handler that is cofigured on the installation of the package and can be injected for use in any wanted service. This is the JwtHandler. This handler will allow us to manipulate, encrypt and extract information from Json Web Tokens.

Here are some interesting references to continue learning about this topic:

You can use a large number of attributes, some are optional, for example to define the route of end-points [Route("/GetSomething")] and other are required, like [ApiController] to indicate that the class is an API controller.

] ==== [HttpOptions]

This attribute identifies an API controller end-point that support the HTTP OPTIONS request. The HTTP OPTIONS method is used to get information about the communication options available for a specific URL or server.

] ==== [AllowAnonymous]

AllowAnonymous allows any type of user (authorized or unauthorized) to access the information provided by the end-point. This attribute can be specified for controller class or for individual end-points. Specifying it for individual end-points will override the controller attribute. An example could be:

] ==== [Authorize]

Authorize only enables you to restrict access to requests with an authorization specified in the header. This attribute can be specified for controller class or for individual end-points. Specifying it for individual end-points will override the controller attribute. You can specify different properties to the attribute:

For example, lets create a controller that is authorized only for users with role 'Admin' and 'Tester' provided in 'Bearer' type authentication:

[[devonfw-guide_devon4net.wiki_howto.asciidoc_enablecors—​disablecors]]] ==== [EnableCors] & [DisableCors]

You can enable a Cors policy for controller or individual end-points. Specifying it for individual end-points will override the controller attribute. You will need to specify the policy you want to enable. This policy will need to be described in the appsettings.{environment}.json.

For example, lets create a CORS policy named 'CorsPolicy' and enable it for a controller, and disable it for a method:

Here are some interesting references to continue learning about this topic:

Keycloak is an open-source tool that provides identity and access management providing highly secure properties to your application. It supports multiple protocols such as OAuth and OpenID. It has full support for SSO (Single Sign-On and Single Sign-Out) and third party Social Identity Providers such as Google, Twitter, Facebook…​

You can also connect it to some type of user database if you already have one for your client. This allows you to interconnect multiple applications through same users and data.

One of the most interesting features is the GUI available through and end-point that allows you to configure and manage your Keycloak settings and properties.

Long story short, Keycloak is a server that manages all your user related interactions, such as roles, groups, access tokens…​ so you can focus in developing your application and don’t have to reinvent the wheel.

For this example we will be running the Keycloak docker image and exposing it in a local port.

To start the Keycloak Server run the following command:

This will start the keycloak server in a docker image. It will be availabe in your localhost port 8080. As you can also see by the command, it will create an initial admin user with username admin and password admin. You can sign in navigating to the address localhost:8080 and using this initial credentials.

In Keycloak, a realm is the same as an environment. It enables the creation of exclusive groups of users and applications. In Keycloak, there is just one realm by default, named master. This is for managing Keycloak only, therefore don’t use it for your own programs.

To create a realm you can hover the small arrow where it says Master in the dashboard and click on Add realm.

Choose a name, for this example we will name it MyRealm, and then click Create.

Now when your realm is selected, you will be able to configure it through the Realm Settings tab in the left side menu.

A client, in Keycloak is equivalent to an application. You can add multiple applications and all can use the same users, groups, roles…​

Now fill the form choosing at least a required client id. You can also select the protocol you will be using:

To create a new user follow the next steps:

Groups in Keycloak allow you to manage a common set of attributes and role mappings for a set of users. Let’s create a new group and add some users inside:

When your service relies on realm roles or does not rely on the token’s roles at all, a hardcoded audience can be useful. A hardcoded audience is a protocol mapper that adds the client ID of the specified service client to the token as an audience. If you want to use a different audience than the client ID, you can use any custom value, such as a URL.

The protocol mapper can be added directly to the frontend client. When the protocol mapper is directly added, the audience is always added as well.

For better control over the protocol mapper, you can create the protocol mapper on the dedicated client scope:

For create the mapper itself follow the nexts steps:

In the next screen configure the Mapper as follows:

This template allows you to understand the authentication and authorization process using Keycloak:

In the Download section you will find a sample that you can use as a template for integrating Keycloak in your application.

The template shows an example of a School with two types of entities, Student and Teacher, the teachers also have the Administrator role, that allows to access to their Student list.

In the application you will be able to authenticate yourself through a username and password, and this will give you an authorization token that will allow you to use the application with a certain role.

To configure Anti-Forgery protection in a devon4net project, you must set UseXsrf property in devonfw configuration section to true. You will find this section in appsettings.json:

Setting this property to true will allow you to use IAntiforgery interface through the service provider and dependency injection in your project.

In the devon4net Web API Templaate you will be able to find an example of controller using this protection. You can inject the IAntiforgery interface in the controller constructor like so:

Now you can access its methods to manage this special token. For creating one we can use GetAndStoreTokens(HttpContext httpContext) method available on IAntiforgery, and store it in the cookies as shown below:

This will be done through a GET request. Now we can vaklidate this token in a controller thanks to the attribute [ValidateAntiForgeryToken]:

We will be using Postman to test the use of the controller, as you can see in the next figure, if we try to access the end-point protected by the antiforgery token validation we get an error:

That is beacuse no valid token in XSRF-TOKEN header is specified. Lets access the end-point we created to provide an XSRF token:

Now that we have the token we can specify it in the request header as shown in the next figure:

Here are some interesting references to continue learning about this topic:

You can import a database in your favourite type of schema, but for this example we will be using SQL Server and Visual Studio 2022.

For this example we used Microsoft SQL Server Management Studio to create our database and provide us with a local database connection.

Before starting with the scaffolding you will need to install the following NuGet packages in your destination project.

Run the following command to execute the scaffolding operation:

In our case, before doing the scaffolding we had something like this:

And the scaffolding produced the following directory tree:

If you do not specify -Tables, -ContextDir and -OutputDir all of the tables will be scaffolded and the default directories will be the project directory.

Now that we have our context we will need to add it either in Program.cs or SetupDatabase method in DevonConfiguration class.

As we are using Devon, we will need to go to Devon4Net.Application.WebAPI.Implementation.Configuration.DevonConfiguration and add the folowing line in SetupDatabase method:

Where:

List of supported databases:

As you will find all the information in the component documentation, we prepared a video using LiteDb in a very short example:

The following table shows the options that can be configured.

To use specflow you will need to add the Specflow extension to your Visual Studio 2022. This way you can use it in any of your projects. For that open visual studio and navigate to Extensions > Manage Extensions.

This will open the extension manager, where you will have to search for the 'SpecFlow' extension and hit download:

Hitting download will schedule the extension installation. At the time when you close VS2022, you will be able to install the extension by clicking Modify in the pop-up window shown below:

To create a specflow project for testing, first we will need to have something to test. In this example we will test a Calculator class that we created inside a class library project in an empty solution like shown in the following image:

Where, the Calculator class implementation is:

Once we have the Calculator ready, we need to create a Specflow project. For that you can Right click on the solution > Add > New Project…​. This will open a window where you can search the specflow project as shown in the next image:

When creating the project you will be able to choose the .Net version that you are using, the library for the tests and if you want to use FluentAssertions library. For this example we will use the configuration shown below:

The specflow template comes with a calculator test implemented, this is their example. But we will create the files from scratch so you know how to complete your testing project.

As you can see also the template comes with a folder structure defined, you can redifine it as you want but this is the recommended one.

To create a new test using specflow, you can add a new item to your project by Right click in any directory on the project > Add > New item…​:

You can type specflow in the search bar to look for the items available thanks to the library and select Feature File for Specflow. You can create a test there in Gherkin syntax:

Once you have your test created you can build the project by navigating to Build > Build Solution. You will see that the test appears in a purple color, this is because it is not mapped to a definition yet. You can automatically create the definition by Right clicking inside the feature file > Define Steps.

This will open the following window:

Once you press Create the test will no longer appear in purple and will be shown in a white color. This is because now they have a definition. You can also do this manually creating a class and marking it with the [Binding] attribute.

This class will need to define the test steps such as Gherkin syntax can be transformed into C# code. You can implement this class as follows to test the Calculator:

Now build the solution again to be able to run the tests.

To run the tests you can navigate to Test > Test Explorer:

By clicking the green play button you can run the tests and see the results as shown in the image above.

SpecFlow Living Documentation is a set of tools that allows you to share and collaborate on Gherkin Feature Files. It gives you the option to generate and share an html interactive file. You can do this directly for Azure DevOps or using a CLI (Command Line Interface). In this guide you will learn how to do this with the CLI continuing with the Calculator example.

We have to setup two services in order to implement Circuit Breaker pattern, in this scenario, we’re creating a basic application that connects two services that are similar.

The preceding example is covered in detail in this video lesson:

There are several methods to configure the RabbitMQ server, depending on your operating system.

In this tutorial, we will show you how to run a server via Docker, for testing purposes. If you want further information on how to configure and install the RabbitMQ server in a specific operating system, please consult the official RabbitMQ documentation

First you must have docker installed on your machine. Run the following command to start the server:

This command shows several options parameters:

The server will listen on port 5672, and you may access the management plugin at the following url:

http://localhost:15672/

You may customize your Docker container as you like, please see the official Docker image documentation for more information.

To use Kafka you need to have an active Kafka server. There are multple ways to use a kafka server, we are using a docker image but you can choose any desired form.

Once you have an Apache Kafka Server up and running you will need to create a project using the Devon4Net template or add Devon4Net.Infrastructure.Kafka NuGet package reference to your project.

When you have both things ready, you can start by adding the following line in your Program.cs

Now is the time to configure all the producers and consumers you will be using in the application. You will later be relating this configuration to the Consumer and Producer Handler classes. For that you will need to complete the following configuration in appsettings.{environment}.json file with your preferred parameters.

After defining the configuration in the appsettings.{environment}.json now you can create your handlers extending the ones available in the Kafka component.

For the producer you can do something as the following:

You will need to add this handler to your dependencies. For that you can use the following method, and include the Id of the configuration as a parameter:

Now you can use the handler in any constructor via dependency injection:

For example, in the previous piece of code, you can see how we are delivering a message to the Kafka server using a POST method in our API. This is done thanks to the SendMessage method.

The consumer is a little different, as you can see in the following piece of code, you will need to override the HandleCommand method. This will handle the process of consuming new messages to which the consumer is subscribed.

Similar to the producer, the Consumer also needs to be related to a configuration via the Id as follows:

You also have message definitions, which is an aggregate containing a set of typed fields:

The previous example defines a type Person with name, id and email. Each field needs a unique identifier, which is the number shown after the =. The data types are the standard ones including bool, int32, float, double, and string.

Let’s say that this Person can have many phone numbers, we could do something like:

As you can see, if a field is repeated, the field may be repeated any number of times, including 0. You can also define enum types if you want one of your fields to have one of a predefined list of values.

If you want to use your message types with an RPC system, you may specify an RPC service interface in a.proto file, and the protocol buffer compiler will create code and stubs in your preferred language.

For example you could define the following contract:

In this case we will have a SearchService class with a Search method that accepts a SearchRequest and returns a SearchResponse. Both (SearchRequest and SearchResponse) need to be mapped to a message.

The following example shows the complete .proto file used in the devon gRPC templates.

A Lambda Function is a function or piece of code that runs in AWS without having to configure or manage a server. You can setup your code and deploy it to the AWS Lambda Service and can trigger and be triggered from other AWS Services.

It supports numerous programming languages ​​among which is .NET.

In devon4Net you have some AWS templates available, to install them you can run the following command.

After this you will be able to create a project using the template provided by devon4net that include the components you need to start developing your first lambda function.

You will also need to install the AWS tools for Visual Studio. Run the following command to install the tools:

Or check if a new version is available in case you have already installed it:

Now that everything is installed you can start by creating your project using the template, for that:

This three steps will create the project where we will develop our function. For this tutorial, we will focus in the Lambda part of the template. That means, that we will only be using the Devon4Net.Application.Lambda project present in the template:

As you can see in the screenshot above, you already have some example functions that are already working:

Each directory has the following subdirectories:

We will follow the same file structure than the examples that are already in the template. For the example we will create a Calculator that will do a mathematical division of two numbers, dividend and divisor; and will produce two other numbers, quotient and remainder.

You will need to install the AWS Lambda tools. Run the following command to install the tools:

Or check if a new version is available in case you have already installed it:

For deploying the lambda function using the Amazon Web Services CLI (Command Line Interface) first you will need to install the tool. You can check if you already have it by running the following command in your preferred terminal:

If you don’t see any output, please refer to the following guide for Installing or updating the latest version of the AWS CLI.

For deploying the lambda function using the AWS Toolkit for Visual Studio first you will need to install the plugin.

For installing it, please refer to the following documentation Install the AWS Toolkit for Visual Studio.

A serverless architecture is a way to build and run applications and services without having to manage infrastructure. Your application still runs on servers, but all the server management is done by AWS.

In devon4Net you have some AWS templates available, to install them you can run the following command.

Following that, you will be able to build a project using the devon4net template that includes the components you need to begin building your first AWS serverless WebAPI.

Now that everything is in place, you may begin by creating your project using the template:

These three procedures will result in the creation of the project in which we will develop our serverless WebAPI. For that, we will just use the project 'Devon4Net.Application.WebAPI.AwsServerless' from the template:

[[devonfw-guide_devon4net.wiki_howto.asciidoc_step-1---configure-it-in-appsettings.{environment}.json]] ==== Step 1 - Configure it in appsettings.{environment}.json

Amazon DynamoDB is a fully managed NoSQL database service that provides fast and predictable performance with seamless scalability. In DynamoDB, tables, items, and attributes are the core components that you work with. A table is a collection of items, and each item is a collection of attributes. DynamoDB employs primary keys to uniquely identify each item in a table, as well as secondary indexes to provide query flexibility. DynamoDB supports two different types of primary keys:

In devon4net you may work with two types of repositories:

You need to install the AWSSDK.DynamoDBV2 nuget, for that you can run the following command in the Package Manager Console:

Devon4net includes the DynamoSearchCriteria class, which makes it easier to use the DynamoDB SDK searching methods.

In DynamoDB SDK, there are two possible operations:

In devon4net you must create a new instance of DynamoSearchCriteria class, for accessing those methods:

The AddSearchCriteria and AddQueryCriteria methods have fairly similar syntax, as shown in the code above.

AWS Cloud Development Kit (CDK) is an open-source software development framework to define your cloud application resources using familiar programming languages. This framework allows you to define all your AWS infrastructure as readable code. This process is known as Infrastructure as Code (IaC) and consists in provisioning and managing infrastructure for your software solutions through code, instead of doing so manually.

This means that you can easily modify, distribute and reproduce configurations. In addition, by including infrastructure as code:

In a real project, we will use AWS services such as DynamoDB databases, S3 buckets, multiple lambdas, and so on. Similarly, we will be working in a variety of work environments.

Devon4Net, with the help of the CDK, allows us to treat these services as code (IaC), which allows us to take all of this service structure and replicate it in another environment that interests us, saving development time and treating this copy of your AWS services as a backup.

In Devon4Net, we can use a standarized json file to configure the AWS CDK service, this json will be translated into readable code for the CDK framework.

AWS CDK official documentation