docs/en/studio/running-applications.md
//[doc-seo]
{
"Description": "Learn how to use the ABP Studio's Solution Runner to run applications, manage tasks, and organize projects with customizable profiles."
}
//[doc-nav]
{
"Next": {
"Name": "Monitoring Applications",
"Path": "studio/monitoring-applications"
}
}
Use the Solution Runner to easily run your application(s), execute tasks, and set up infrastructure. You can create different profiles to organize projects based on your needs and teams. Simply navigate to the Solution Runner panel in the left menu.
The Solution Runner contains two tabs:
The project structure might be different based on your selection. For example MVC microservice project, looks like the following. You can edit the tree structure as you wish.
We can create different profiles for each teams or scenarios, which is provide us to organize our tree structure as needed. With this way each profile contains their own folder and application tree structure. We can collapse or expand the entire tree using the up and down arrow icons. The Default profile comes with the project creation, includes all projects in the tree to manage at once. You can view all profiles in the combobox and change the current profile. To edit, click the gear icon located on the right side.
It opens the Manage Run Profiles window. You can edit/delete existing profiles or add a new one.
When you click Add New Profile, it opens the Create New Profile window. You can provide an arbitrary profile name, which should be unique among the profiles. Additionally, the name should only contain letters, numbers, underscores, dashes, and dots in the text. When you create a new profile, it stores the JSON file at the specified path. You can specify the path abp-solution-path/etc/abp-studio/run-profiles for microservice projects or abp-solution-path/etc/run-profiles for other project types to adhere to the standard format. You can also define Metadata and Secrets key-value pairs. Click OK button to save profile.
When a profile is edited or deleted while running some applications, those applications will be stopped. However, applications running under a different profile will continue to run unaffected. Lastly, if we add a new profile, all applications running under existing profiles will be stopped.
The Applications tab allows you to manage and run your applications. The solution runner contains 4 different types to define tree structure:
team-1 and team-2. team-1 want to see the only Administration and Identity service, team-2 see the Saas and AuditLogging services. With that way each team see the only services they need to run. In this example Default profile Acme.BookStore (Default) comes out of the box when we create the project.services folder for our microservice projects. We can also use nested folder if we want apps, gateways and services are the folders in current(Default) profile.Acme.BookStore.AuthServer, Acme.BookStore.Web, Acme.BookStore.WebGateway, etc., are C# applications.After selecting the current profile, which is the Default profile that comes pre-configured, we can utilize the tree items. This allows us to execute collective commands and create various tree structures based on our specific needs. You can navigate through the root of the tree and right-click to view the context menu, which includes the following options: Start All, Stop All, Build, Add, and Manage Start Actions.
We can start/stop the applications with these options. Go to the root of the tree and right-click to view the context menu:
Start All: Start all(CLI, C#) applications.Stop All: Stop all(CLI, C#) applications.You can change the current profile while applications are running in the previous profile. The applications continue to run under the previous profile. For example, if we start the
Acme.BookStore.AdministrationService,Acme.BookStore.IdentityServiceapplications when the current profile is team-1 and after changing the current profile to team-2 the applications continue to run under team-1.
We can use common dotnet commands in this option. Go to the root of the tree and right-click to view the context menu, in this example Acme.Bookstore(Default) -> Build, there are 4 options available:
Build All: Builds each C# applications.Graph Build: Builds each C# applications with graphBuild option.Restore: Restores the dependencies for C# applications.Clean: Cleans the output of the previous build for C# applications.Since Solution Runner may contain numerous C# projects, the Build options uses the Background Tasks, ensuring a seamless experience while using ABP Studio.
We can add 4 different item types to Profile for defining the tree structure. Those options are C# Application, CLI Application, Docker Container, and Folder.
Note: The
Docker Containeroption is only available when right-clicking the profile root. When right-clicking a folder, onlyC# Application,CLI Application, andFolderoptions are available.
When we go to the root of the tree and right-click, in this example Acme.BookStore(Default) -> Add -> C# Application it opens the Add Application window. There are two methods to add applications: This solution and External. To add via the This solution tab, follow these steps:
Select application: First we have to select an application, you have the option to add the same application multiple times.Name: Give an arbitrary name to see in solution runner. This name should be unique for each profile even the selected application already exists.Launch url: Is the url when we want to browse.Kubernetes service: If you're not using the Kubernetes panel leave it empty. It's necessary for browse, when we connect the kubernetes cluster we should browse the kubernetes services instead Launch url. In microservice template this option already configured and you can copy the existing regex pattern from your selected application properties. If you create a custom helm chart you can also give the regex pattern that matches with your helm chart kubernetes service name.You can click the OK button to add the C# application to the profile.
The C# project doesn't have to be within the current Solution Explorer, it can even be outside. Also the project type could be anything such as Console App, ASP.NET Core Razor Pages, etc. To add it, click on the External tab in Add Application window.
Path: Provide the path to the .csproj file you wish to add. The path will be normalized, allowing the project location to be flexible, as long as it's accessible from the current ABP Solution.Name: Give an arbitrary name to see in solution runner. This name should be unique for each profile.Launch url: This is the url when we want to browse. But if the added project doesn't have launch url we can leave it empty.Kubernetes service: If you're not using the Kubernetes panel leave it empty. But if there is a helm chart for added application we should give the correct regex pattern. It's necessary for browse, when we connect the kubernetes cluster we should browse the services instead Launch url. Give the matching regex pattern for your helm chart kubernetes service name.You can click the OK button to add the C# application to the profile.
We can add any powershell file to execute from the solution runner. With this flexibility we can prepare our infrastructure environment such as Docker-Dependencies or run different application types like Angular. You can add CLI applications with root of the tree and right-click, in this example Acme.BookStore(Default) -> Add -> CLI Application.
Name: Give an arbitrary name to see in solution runner. This name should be unique for each profile.Working directory: Provide the start and stop commands file directory path. The path will be normalized, allowing the folder location to be flexible, as long as it's accessible from the current ABP Solution.Start command: Give the poweshell file name that we wanna execute when we click the Run -> Start. We should start with local path prefix ./ if the powershell file directory in Working directory or if it's in nested folder we can give the path like ./sub-path/start.ps1. Also we can give the argument like ./start.ps1 -parameter value -parameter2 value2.Stop command: If there is a different stop command such as for docker up.ps1 and down.ps1 commands. We should give the stop powershell file name that we wanna execute when click the Run -> Stop. We should start with local path prefix ./ if the powershell file directory in Working directory or if it's in nested folder we can give the path like ./sub-path/stop.ps1. Also we can give the argument like ./stop.ps1 -parameter value -parameter2 value2.Launch url: If there's a launch URL at the end of this starting process, such as for angular project publishing an app at http://localhost:4200, to enable the browse option, we should provide the Launch url.If the stop command isn't provided, the starting process automatically ends upon the completion of the executed start command. However, if the start command keeps running, for instance, with a command like
yarn start, it will continue to run until we manually click Run -> Stop.
You can click the OK button to add the CLI application to the profile.
When adding applications directly to the root of the tree, it can become disorganized, especially with numerous projects. Utilizing a folder structure allows us to organize applications more efficiently. This method enables executing collective commands within a specified folder. When we go to root of the tree and right-click, in this example Acme.BookStore(Default) -> Add -> Folder it opens New folder window.
Folder name: Give the folder name that we wanna see in solution runner. We can create nested folder with / character. This is a solution runner profile folder so, it doesn't create a real folder. Ensure each folder name is unique for each profile.You can click the OK button to add the folder to the profile.
This command will open a dialog where you can set start actions and start orders of sub-applications and sub-folders.
You can order the applications by dragging the icon in the first column. In the screenshot above, applications & folders are ordered like this: Applications under infrastructure > Applications under services > Applications under gateways > AuthServer > Angular. You can also set starting order and other actions for each folder by performing right click > Manage Start Actions on them.
Start and Don't start. This is usefull if you want to exclude applications from batch start.right click > properties on applications.right click > properties on applications.We already now why we need folder in the previous section, we can use collective commands within this folder items. To do that go to folder and open the context menu by right-clicking, which includes 5 options Start, Stop, Build, Add, Manage Start Actions, Rename and Delete.
You can see the context menu by right-clicking Folder. It will start/stop all the applications under the folder.
Folder -> Build context menu, it's the similar options like Acme.BookStore(Default) -> Builds options there are 4 options available. The only difference between them it's gonna be execute in selected folder.
Folder -> Add context menu, it's the same options like Acme.BookStore(Default) -> Add there are 3 options avaiable. The only difference, it's gonna add item to the selected folder.
The .NET icon indicates that the application is a C# project. After we add the C# applications to the root of the tree or folder, we can go to any C# application and right-click to view the context menu; Start, Stop, Restart, Build, Browse, Health Status, Requests, Exceptions, Logs, Copy URL, Properties, Remove, and Open with.
When you start the C# application, you should see a chain icon next to the application name, that means the started application connected to ABP Studio. C# applications can connect to ABP Studio even when running from outside the ABP Studio environment, for example debugging with Visual Studio. If the application is run from outside the ABP Studio environment, it will display (external) information next to the chain icon.
It's the similar options like root of the tree options. The only difference between them it's gonna be execute the selected application.
When the C# application is connected to ABP Studio, it starts sending telemetry information to see in one place. We can easily click these options to see the detail; Browse, Health Status, Requests, Exceptions, Events and Logs.
Browse: ABP Studio includes a browser tool for accessing websites and running applications. You can click this option to view the application in the ABP Studio browser. However, this option is only accessible if the application is started.Health Status: A submenu that provides health monitoring options when Health Check endpoints are defined:
Requests: It opens the HTTP Requests tab with adding the selected application filter. You can view all HTTP Requests received by your applications.Exceptions: We can display all exceptions on this tab. It opens the Exceptions tab with selected application.Events: Opens the Events tab filtered by this application. You can view all Distributed Events sent or received by this application.Logs: Clicking this option opens the Logs tab with adding the selected application filter.We can open the Application Properties window to change Launch url, Health check endpoints, Kubernetes service and run information. To access the Application Properties window, navigate to a C# application, right-click to view the context menu, and select the Properties option.
bookstore-identity-service, you can use .*-identity-service or bookstore-identity.* as the pattern. For microservice templates, this is pre-configured./ to use the home page of the application as health check endpoint.The Open with submenu provides options to open the application project in external tools:
You can add custom commands that appear in the context menu of Solution Runner items (root, folders, and applications). These commands allow you to automate custom workflows and scripts. For details on creating and managing custom commands, see the Custom Commands documentation.
CLI applications uses the powershell commands. With this way we can start and stop anything we want. After we add the CLI applications to root of the tree or folder, we can go to any CLI application and right-click to view the context menu.
Start: Starts the application. Once it is started, Start and Restart options will be available.Browse: This option is available when a Launch URL is specified upon adding the CLI application. It opens the Browse tab, can be clicked while the application is running.Logs: It opens the Logs tab, we can see the logs for Start and Stop commands.Copy URL: This option copies the Launch URL of the selected application. It is visible if there is a specified Launch URLRemove: This option allows you to delete the selected application.When CLI applications start chain icon won't be visible, because only C# applications can connect the ABP Studio.
Each Docker container represents a .yml file. Each file can be run on UI individually. A file may contain one or more services. To start/stop each service individually, we recommend to keep services in separate files.
An example rabbitmq.yml container file:
volumes:
bookstore_rabbitmq:
networks:
bookstore:
external: true
services:
rabbitmq:
container_name: rabbitmq
image: rabbitmq:3.12.7-management-alpine
volumes:
- bookstore_rabbitmq:/var/lib/rabbitmq
networks:
- bookstore
ports:
- "15672:15672"
- "5672:5672"
Note: We suggest to use
container_nameproperty in your services. Otherwise, tracking the container may not be possible in some cases.
To add this file to containers, we can use Add Docker Container menu:
It will open a simple dialog with a file picker:
Then we have the rabbitmq on the Studio UI under containers:
Name of the yml file is used as label in the UI, so we recommend to create the file with the name of service inside.
If the yml file contains multiple services, they will be represented as a single container with the file name. In this case, when we start/stop it, all services inside the file will be started/stopped.
If a service is shut down externally, it will be shown as
Stoppedin the UI. In this case you can start them again. If it is constantly stopping, there may be a problem in theymlfile.
It may take stuck in
startingstate a while to download images if they don't exist.
A warning icon is displayed when a service is stopped externally inside the container. In this case, yo can restart the application on Studio UI:
In properties dialog, you can set the name of docker compose stack name of the containers. In the example above, it is set as BookStore-Containers. In Docker Desktop UI the containers are stacked under that name. Exmple:
You can manually run applications using Docker Compose. This allows for easy setup and management of multi-container Docker applications. To get started, ensure you have Docker and Docker Compose installed on your machine.
Refer to the Deployment with Docker Compose documentation for detailed instructions on how to configure and run your applications using docker-compose.
Note: The Docker Compose is not available in the ABP Studio interface.
The Tasks tab in the Solution Runner allows you to define and execute tasks for your solution. You can run initialization tasks after solution creation, create reusable tasks that can be executed on demand, and optionally configure tasks to run automatically when a solution is opened. Navigate to the Solution Runner panel in the left menu and select the Tasks tab.
The task structure might vary based on your solution template. ABP Studio solution templates come with pre-configured tasks like Initialize Solution.
The Tasks panel has a tree structure similar to the Applications panel:
Tasks are associated with the current Profile, just like applications. When you switch profiles, the task configuration may differ based on what's defined in each profile.
When you create a new solution using ABP Studio templates, the following tasks are automatically configured in the Default profile:
The Initialize Solution task performs the initial setup required after creating a new solution or cloning an existing one from source control. This task is configured with the Run on solution initialization (1 time per computer) behaviour, meaning it runs automatically only once per computer when the solution is initialized.
The initialization typically includes:
abp install-libs)This task is designed to be idempotent, meaning it can be run multiple times without causing issues.
The Migrate Database task runs the database migration for your solution. This is useful when you need to apply new migrations after pulling changes from source control or when you've added new migrations yourself.
Unlike the Initialize Solution task, the Migrate Database task is not configured to run automatically on solution open by default.
To add a new task, right-click on the root item (solution name) in the Tasks panel and select AddTask item.
This opens the Add Task window where you can configure the task:
./ if the script is in the working directory (e.g., ./scripts/my-task.ps1). You can also pass arguments like ./my-script.ps1 -param value.Click OK to add the task to the profile.
Once tasks are added to the panel, you can manage them using the context menu. Right-click on a task to see the available options:
Unlike applications, tasks do not automatically restart if they fail or stop. A task can complete its execution and stop itself (like running a database migration), or it can continue running until manually stopped.
Click Logs to view the task's output in a dedicated window. This shows the console output from the task's execution, which is helpful for debugging or monitoring progress.
Click Properties to open the task configuration window where you can modify the task settings:
Select Remove to delete the task from the profile. This action only removes the task configuration; it does not delete any script files.
Tasks configured with Run on solution open behaviour are automatically executed every time you open the solution in ABP Studio. This is useful for:
When the solution is opened:
Tasks configured with this behaviour should be idempotent, meaning running them multiple times should not cause errors or duplicate operations.
Tasks configured with Run on solution initialization (1 per computer) behaviour are executed only once per computer when the solution is first opened. After the initial execution, the task will not run automatically on subsequent solution opens. This is ideal for:
This behaviour is particularly useful for:
The Initialize Solution task that comes with ABP Studio templates uses this behaviour by default. It checks if NPM packages are already installed before running
abp install-libsand performs other initialization steps only when necessary.
Tasks are stored in the run profile JSON files (*.abprun.json). The task configuration looks like this:
{
"tasks": {
"Initialize Solution": {
"behaviour": 2,
"startCommand": "./initialize-solution.ps1",
"workingDirectory": "../../scripts",
"shortDescription": "Installs required UI libraries and creates required certificates."
}
}
}
You can manually edit these files if needed, but it's recommended to use the ABP Studio UI for managing tasks to ensure proper formatting and validation.