@ -27,7 +27,7 @@ If you want to open any of these tabs in separate window, just drag it from the
## Collecting Telemetry Information
There are two application [types](./running-applications.md#abp-studio-running-applications): C# and CLI. Only C# applications can establish a connection with ABP Studio and transmit telemetry information via the `Volo.Abp.Studio.Client.AspNetCore` package. However, we can view the *Logs* and *Browse* (if there is a *Launch URL*) for both CLI and C# application types. Upon starting C# applications, they attempt to establish a connection with ABP Studio. When connection successful, you should see a chain icon next to the application name in [Solution Runner](./running-applications.md#run-1). Applications can connect the ABP Studio with *Solution Runner* -> *C# Application* -> *Run* -> *Start* or from an outside environment such as debugging with Visual Studio. Additionally, they can establish a connection from a Kubernetes Cluster through the ABP Studio [Kubernetes Integration: Connecting to the Cluster](../get-started/microservice.md#kubernetes-integration-connecting-to-the-cluster).
There are two application [types](./running-applications.md#applications): C# and CLI. Only C# applications can establish a connection with ABP Studio and transmit telemetry information via the `Volo.Abp.Studio.Client.AspNetCore` package. However, we can view the *Logs* and *Browse* (if there is a *Launch URL*) for both CLI and C# application types. Upon starting C# applications, they attempt to establish a connection with ABP Studio. When connection successful, you should see a chain icon next to the application name in [Solution Runner](./running-applications.md#start--stop--restart). Applications can connect the ABP Studio with *Solution Runner* -> *C# Application* -> *Run* -> *Start* or from an outside environment such as debugging with Visual Studio. Additionally, they can establish a connection from a Kubernetes Cluster through the ABP Studio [Kubernetes Integration: Connecting to the Cluster](../get-started/microservice.md#kubernetes-integration-connecting-to-the-cluster).
You can [configure](../framework/fundamentals/options.md) the `AbpStudioClientOptions` to disable send telemetry information. The package automatically gets the [configuration](../framework/fundamentals/configuration.md) from the `IConfiguration`. So, you can set your configuration inside the `appsettings.json`:
@ -91,13 +91,13 @@ Kubernetes integration in ABP Studio enables users to deploy solutions directly
This pane is dedicated to managing [Helm](https://helm.sh/) charts, which are packages used in Kubernetes deployments. It simplifies the process of building images and installing charts.
"Description": "Learn how to use the ABP Studio's Solution Runner to efficiently run applications and organize projects with customizable profiles."
"Description": "Learn how to use the ABP Studio's Solution Runner to run applications, manage tasks, and organize projects with customizable profiles."
}
```
# ABP Studio: Running Applications
# ABP Studio: Solution Runner
````json
//[doc-nav]
@ -17,19 +17,16 @@
}
````
Use the *Solution Runner* to easily run your application(s) 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.
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 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.
The Solution Runner contains two tabs:
The solution runner contains 4 different types to define tree structure.
- **Applications**: For managing and running your applications.
- **Tasks**: For managing tasks that can be executed on demand or automatically when the solution is opened.
- **Profile**: We can create different profiles to manage the tree as our needs. For example we can create 2 different profile for `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.
- **Folder**: We can organize the applications with *Folder* type. In this example, we keep services in `services` folder for our microservice projects. We can also use nested folder if we want `apps`, `gateways`` and `services` is the folders in current(`Default`) profile.
- **C# Application**: We can add any C# application from our [Solution Explorer](./solution-explorer.md). If the application is not in our solution, we can add it externally by providing the *.csproj* file path. The .NET icon indicates that the application is a C# project. For example, `Acme.BookStore.AuthServer`, `Acme.BookStore.Web`, `Acme.BookStore.WebGateway`, etc., are C# applications.
- **CLI Application**: We can add [powershell](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core) commands to prepare some environments or run other application types than C# such as angular.
- **Docker Container**: We can add Docker container files to control them on UI, start/stop containers individually.
> 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.
## Profile
@ -47,13 +44,23 @@ When you click *Add New Profile*, it opens the *Create New Profile* window. You
> 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.
## Using the Profile
## Applications
The **Applications tab** allows you to manage and run your applications. The solution runner contains 4 different types to define tree structure:
- **Profile**: We can create different profiles to manage the tree as our needs. For example we can create 2 different profile for `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.
- **Folder**: We can organize the applications with *Folder* type. In this example, we keep services in `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.
- **C# Application**: We can add any C# application from our [Solution Explorer](./solution-explorer.md). If the application is not in our solution, we can add it externally by providing the *.csproj* file path. The .NET icon indicates that the application is a C# project. For example, `Acme.BookStore.AuthServer`, `Acme.BookStore.Web`, `Acme.BookStore.WebGateway`, etc., are C# applications.
- **CLI Application**: We can add [powershell](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core) commands to prepare some environments or run other application types than C# such as angular.
- **Docker Container**: We can add Docker container files to control them on UI, start/stop containers individually.
### Using the Profile
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:
@ -62,7 +69,7 @@ We can start/stop the applications with these options. Go to the root of the tre
> 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.IdentityService` applications when the current profile is *team-1* and after changing the current profile to *team-2* the applications continue to run under *team-1*.
### Build
#### Build
We can use common [dotnet](https://learn.microsoft.com/en-us/dotnet/core/tools) 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:
@ -75,7 +82,7 @@ We can use common [dotnet](https://learn.microsoft.com/en-us/dotnet/core/tools)
> Since *Solution Runner* may contain numerous C# projects, the *Build* options uses the [Background Tasks](./overview#background-tasks), ensuring a seamless experience while using ABP Studio.
### Add
#### Add
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`.
@ -83,7 +90,7 @@ We can add 4 different item types to *Profile* for defining the tree structure.
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:
@ -100,7 +107,6 @@ The C# project doesn't have to be within the current [Solution Explorer](./solut
- `Path`: Provide the path to the .csproj file you wish to add. The path will be [normalized](https://learn.microsoft.com/en-us/dotnet/standard/io/file-path-formats#path-normalization), allowing the project location to be flexible, as long as it's accessible from the current [ABP Solution](./concepts.md#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.
@ -108,7 +114,7 @@ The C# project doesn't have to be within the current [Solution Explorer](./solut
You can click the `OK` button to add the C# application to the profile.
#### CLI Application
##### CLI Application
We can add any [powershell](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core) 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*.
@ -124,7 +130,7 @@ We can add any [powershell](https://learn.microsoft.com/en-us/powershell/module/
You can click the `OK` button to add the CLI application to the profile.
#### Folder
##### Folder
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.
@ -134,7 +140,7 @@ When adding applications directly to the root of the tree, it can become disorga
You can click the `OK` button to add the folder to the profile.
### Miscellaneous
#### Miscellaneous
- You can drag and drop folder and application into folder for organization purposes. Click and hold an item, then drag it into the desired folder.
- We can start all applications by clicking the *Play* icon on the left side, similar way we can stop all applications by clicking the *Stop* icon on the left side.
@ -142,7 +148,7 @@ You can click the `OK` button to add the folder to the profile.
- To remove a folder from the tree, open the context menu by right-clicking the folder and selecting *Delete*.
- When starting applications, they continue to restart until the application starts gracefully. To stop the restarting process when attempting to restart the application, click the icon on the left. Additionally, you can review the *Logs* to understand why the application isn't starting gracefully.
### Manage Start Actions
#### Manage Start Actions
This command will open a dialog where you can set start actions and start orders of sub-applications and sub-folders.
@ -154,40 +160,40 @@ You can order the applications by dragging the icon in the first column. In the
- **Build**: This option allows to disable/enable build before starting the application. If you are working on a single application, you can exclude the other applications from build to save time. This option can also be set by performing `right click > properties` on applications.
- **Watch**: When enabled, changes in your code are watched and dotnet hot-reloads the application or restarts it if needed. This option also can be set by performing `right click > properties` on applications.
## Folder
### Folder Context Menu
We already now why we need folder in the [previous](./running-applications.md#folder) 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`.
We already now why we need folder in the [previous](#folder) 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.
### Build
#### Build
*Folder* -> *Build* context menu, it's the [similar](#build) 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](#add) options like *Acme.BookStore(Default)* -> *Add* there are 3 options avaiable. The only difference, it's gonna add item to the selected folder.
- You can rename a folder with *Folder* -> *Rename*.
- You can delete a folder with *Folder* -> *Delete*.
## C# Application
### C# Application
The .NET icon indicates that the application is a C# project. After we [add](#c-application) 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`.
@ -195,13 +201,13 @@ The .NET icon indicates that the application is a C# project. After we [add](#c-
> 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.
### Build
#### Build
It's the [similar](#build) 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`.
@ -216,11 +222,11 @@ When the C# application is connected to ABP Studio, it starts sending telemetry
- `Events`: Opens the *Events* tab filtered by this application. You can view all [Distributed Events](../framework/infrastructure/event-bus/distributed) sent or received by this application.
- `Logs`: Clicking this option opens the *Logs* tab with adding the selected application filter.
### Properties
#### Properties
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.
- **Launch URL**: The URL used when browsing the application. This is the address where the application is accessible.
- **Kubernetes service**: A regex pattern to match Kubernetes service names. When connected to a Kubernetes cluster, ABP Studio uses this pattern to find the corresponding Kubernetes service and uses its URL instead of the Launch URL. This applies to *Browse*, *Copy URL*, and *Health UI* features. For example, if your Helm chart creates a service named `bookstore-identity-service`, you can use `.*-identity-service` or `bookstore-identity.*` as the pattern. For [microservice](../get-started/microservice.md) templates, this is pre-configured.
@ -234,7 +240,7 @@ We can open the *Application Properties* window to change *Launch url*, *Health
The *Open with* submenu provides options to open the application project in external tools:
@ -254,7 +260,7 @@ You can add custom commands that appear in the context menu of Solution Runner i
- You can change the target framework by right-click the selected application and change the *Target Framework* option. This option visible if the project has multiple target framework such as MAUI applications.
- To remove an application from the tree, open the context menu by right-clicking the application and selecting *Remove*.
## CLI Application
### CLI Application
CLI applications uses the [powershell](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core) 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.
@ -268,7 +274,7 @@ CLI applications uses the [powershell](https://learn.microsoft.com/en-us/powersh
> When CLI applications start chain icon won't be visible, because only C# applications can connect the ABP Studio.
## Docker Containers
### Docker Containers
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.
@ -320,9 +326,7 @@ If the `yml` file contains multiple services, they will be represented as a sing
You can manually run applications using [Docker Compose](https://docs.docker.com/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](../solution-templates/layered-web-application/deployment/deployment-docker-compose.md) 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.
> Note: The **Docker Compose** is not available in the ABP Studio interface.
## Tasks
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*.
### Tasks Panel Overview
The Tasks panel has a tree structure similar to the Applications panel:
- **Root**: The root item displays your solution name, similar to the Solution Explorer.
- **Tasks**: Individual tasks that can be started, stopped, and configured.
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.
### Built-in Tasks
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.
- Creating development certificates (for OpenIddict)
- and more... (depends on solution type)
> This task is designed to be idempotent, meaning it can be run multiple times without causing issues.
#### Migrate Database
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.
### Adding a Task
To add a new task, right-click on the root item (solution name) in the Tasks panel and select *AddTask* item.
- **Name**: Provide a unique name for the task. This name will be displayed in the Tasks panel tree.
- **Working Directory**: Specify the directory where the task will be executed. You can use the folder picker to browse and select the directory. The path will be [normalized](https://learn.microsoft.com/en-us/dotnet/standard/io/file-path-formats#path-normalization), allowing flexibility in the folder location.
- **Start Command**: Provide the script or command to execute when the task starts. Use the local path prefix `./` 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`.
- **Task Behaviour**: Select how the task should run: *Manual*, *Run on solution open*, or *Run on solution initialization (1 per computer)*.
- **Short Description**: Short description for the task.
Click *OK* to add the task to the profile.
### Managing Tasks
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:
- **Start**: Executes the task's start command. The task status will change to indicate it's running.
- **Stop**: Stops a running task. If a stop command is configured, it will be executed; otherwise, the process will be terminated.
> 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.
#### Logs
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.
- **Working Directory**: The execution directory for the task.
- **Start Command**: The command to run when starting the task.
- **Task Behaviour**: Select how the task should run: *Manual*, *Run on solution open*, or *Run on solution initialization (1 per computer)*.
- **Short Description**: Short description for the task.
#### Remove
Select *Remove* to delete the task from the profile. This action only removes the task configuration; it does not delete any script files.
### Run On Solution Open
Tasks configured with *Run on solution open* behaviour are automatically executed every time you open the solution in ABP Studio. This is useful for:
- **Environment checks**: Verifying that required services or dependencies are available.
- **Recurring setup**: Tasks that need to run on each session, such as starting background services or refreshing configurations.
When the solution is opened:
1. ABP Studio loads the solution and profiles
2. Tasks marked with *Run on solution open* are queued for execution
3. Tasks execute in the background, and you can monitor their progress in the [Background Tasks](./overview.md#background-tasks) panel
> Tasks configured with this behaviour should be idempotent, meaning running them multiple times should not cause errors or duplicate operations.
### Run On Solution Initialization (1 Per Computer)
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:
- **One-time setup**: Tasks like *Initialize Solution* that install dependencies, run database migrations, or create development certificates.
- **First-time configuration**: Setting up environment-specific configurations that only need to happen once.
This behaviour is particularly useful for:
1. **New team members**: When a developer clones the repository and opens the solution for the first time, all initialization tasks run automatically.
2. **Fresh clones**: Ensures the solution is properly configured without requiring manual intervention.
3. **Avoiding redundant operations**: Prevents running time-consuming setup tasks on every solution open.
> 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-libs` and performs other initialization steps only when necessary.
### Task Configuration in Profiles
Tasks are stored in the run profile JSON files (`*.abprun.json`). The task configuration looks like this:
```json
{
"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.
@ -216,7 +216,7 @@ Implementing `ITransientDependency` registers the `OrderEventHandler` class to t
### Testing the Order Creation
To keep this tutorial simple, we will not implement a user interface for creating orders. Instead, we will use the Swagger UI to create an order. Open the *Solution Runner* panel in ABP Studio and use the *Start* action to launch the `CloudCrm.OrderingService` and `CloudCrm.CatalogService` applications. Then, use the *Start All* action to start the remaining applications listed in the [Solution Runner root item](../../studio/running-applications.md#run).
To keep this tutorial simple, we will not implement a user interface for creating orders. Instead, we will use the Swagger UI to create an order. Open the *Solution Runner* panel in ABP Studio and use the *Start* action to launch the `CloudCrm.OrderingService` and `CloudCrm.CatalogService` applications. Then, use the *Start All* action to start the remaining applications listed in the [Solution Runner root item](../../studio/running-applications.md#startall).
Once the application is running and ready, [Browse](../../studio/running-applications.md#c-application) the `CloudCrm.OrderingService` application. Use the `POST /api/ordering/order` endpoint to create a new order:
Ma Liming
2 weeks ago
GitHub
