Skip to main content

ArconQ Knowledge Base

This guide provides streamlined explanations of key features in ArconQ, with links to further documentation for deeper insights.

SDK and Project Setup​

Adding SDK to VS Project​

Q: How do I add the ArconQ SDK to my Visual Studio project?
A: The ArconQ SDK is distributed as a NuGet package called ArconQ.SDK. To add it to your project:

  1. Add the Macrix public repository (https://nexus.macrix.eu/repository/arq-nuget/) to your Package Sources in NuGet Package Manager.
  2. Alternatively, you can use the command: dotnet nuget add source https://nexus.macrix.eu/repository/arq-nuget/ -n Macrix.ArconQ

Using Project Templates​

Q: How can I create a sample ArconQ application using project templates?
A: To use ArconQ project templates:

  1. Ensure you've added the package source as described in the SDK configuration.
  2. Install the templates using: dotnet new install ArconQ.Project.Templates
  3. You can then create a new project using the template in Visual Studio or via command line.

Minimal API vs Standard API​

Q: What's the difference between Minimal API and Standard API in ArconQ?
A: Minimal API is a new feature in .NET 6 that allows for creating simple applications with less configuration, using a function-based approach for defining endpoints. Standard API is the traditional approach with more features and tools like controllers and routers for complex applications. Minimal API is better for rapid prototyping and simple apps, while Standard API offers more control and customization for complex applications. For more details, see the Minimal API vs Standard API guide.

Q: Can you provide examples of how to start an ArconQ application using both APIs?
A: Here's a basic example for each:

Minimal API:

await ArconQApp.StartAsync(args,
    services => {
        services.AddScoped<IMyService, MyService>();
        services.AddMessageHandler<MyMessageHandler>().WithRoutingId("CustomRoutingId");
        services.AddScheduledJob<MyScheduledJob>().WithIntervalSchedule(10, IntervalType.Seconds);
    });

Standard API:

var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureArconQ(builder.Configuration);
builder.Services.AddArconQ(builder.Configuration);
builder.Services.AddScoped<IMyService, MyService>();
builder.Services.AddMessageHandler<MyMessageHandler>().WithRoutingId("CustomRoutingId");
builder.Services.AddScheduledJob<MyScheduledJob>().WithIntervalSchedule(10, IntervalType.Seconds);
var app = builder.Build();
app.UseArconQ();
app.MapArconQ();
await app.RunAsync();

For more detailed explanations, refer to the Minimal API vs Standard API.

Debug Mode​

Q: What is Debug Mode in ArconQ and how can I use it?
A: Debug Mode allows you to host and debug your app directly on your machine while still connecting to the ArconQ platform. To use it, integrate your app with the ArconQ.SDK.Debug package, configure it in your Program.cs file, and set up the app in ArconQ with debug mode enabled. For step-by-step instructions, check the Debug Mode documentation.

Q: How do I connect my app in Debug Mode to the ArconQ platform?
A: First, initiate the app from the ArconQ platform. Then, start your app hosted outside the ArconQ Cluster. The app status should change from "Disconnected" to "Connected" in the ArconQ UI, indicating a successful connection. For more details, see the Connect your App in debug mode section.

Authorization​

Q: How can I add authorization to my ArconQ app?
A: You can add ArconQ Authorization by including the necessary code in your application. Use the AddArconQAuthorization method in your service configuration and add the UseAuthentication and UseAuthorization middleware. Then, you can use the [Authorize] attribute on your endpoints. For code examples, see the Authorization documentation.

Q: How can I use role-based authorization in my ArconQ app?
A: You can use ArconQ Roles by adding them to the Authorize attribute. For example: [Authorize(Roles = "application-access")]. This ensures that only users with the specific role will have access to the endpoint. Check the Authorization with Roles section for more information.

Public Apps & Custom UIs​

Q: How can I make my app publicly available in ArconQ?
A: To make your app public, use the UsePublicApp method in your app's startup code. Here's an example:

var app = builder.Build();
app.UsePublicApp(builder.Configuration);
app.UseArconQ();
app.MapArconQ();
await app.RunAsync();

Application Development​

Messaging​

Q: How do I send a message using ArconQ messaging?
A: Use the IMessageBus interface. For detailed instructions, see the Messaging documentation.

Q: How can I configure my app to receive messages?
A: Implement the IMessageHandler<T> interface in your service. Refer to the Message Handling documentation for more information.

Scheduling​

Q: How can I create a scheduled job in ArconQ?
A: To create a scheduled job, implement the IScheduledJob interface and register it in your startup code. You can define the frequency using either .WithIntervalSchedule or .WithCronSchedule. Here's a basic example:

public class MyScheduledJob : IScheduledJob
{
    public Task RunAsync()
    {
        // Perform your scheduled job here
        return Task.CompletedTask;
    }
}

// In your startup code:
services.AddScheduledJob<MyScheduledJob>().WithIntervalSchedule(7, IntervalType.Seconds);

For more examples and detailed explanation, see the Scheduling guide.

Q: Can I use CRON expressions for more complex scheduling?
A: Yes, you can use CRON expressions for more complex scheduling needs. Use the .WithCronSchedule method to define your schedule. For example:

// Run every other minute between 8am and 5pm, every day
services.AddScheduledJob<MyScheduledJob>().WithCronSchedule("0 0/2 8-17 * * ?");

For more CRON examples, check the Examples of using CRON schedule section.

App Configuration and Management​

App Configuration​

Q: How do I set up configuration for my app?
A: You can configure your app at three levels:

  1. In the appsettings.json file of your .NET project
  2. In the App Template settings
  3. In the specific App instance settings For a detailed explanation, check the App Configurations guide.

Q: How do I override configuration values from my app's code?
A: You can override values in the App Template or App settings. See the Configuration Inheritance section for more details.

App Feed​

Q: How do I send data to the App Feed?
A: Inject IAppFeedBus into your service and use the SendAsync(T payload) method. For code examples, refer to the App Feed documentation.

Q: Where can I view the App Feed data?
A: Go to the App Details view by clicking on the desired app in the Apps view. The feed will be refreshed in real-time. See the Displaying App Feed payload section for more details.

App Packing​

Q: How do I prepare my app for uploading as an App Template?
A: Build your app, then compress the build output files into a ZIP archive. For detailed instructions, see the Packing App code guide.

App Port Mapping​

Q: How can I expose my app's ports to external clients?
A: Use the App port mapping feature to create NodePort services in Kubernetes. For step-by-step instructions, see the App port mapping guide.

App Template Revisions​

Q: How can I update an existing App Template?
A: Create a new revision of the App Template. You can modify app assets, executable files, startup commands, arguments, and base app configuration. See the Creating a new Revision section for instructions.

Q: How do I delete an App Template revision?
A: First, stop and delete all Apps using the revision. Then, in the App Template Manager, click "DELETE" in the Revisions section and confirm the operation. For more details, check the Deleting revisions section.

App Template Tags​

Q: How can I add metadata to my App Template revisions?
A: Use App Template tags. Tags are additional metadata (keywords or terms) associated with a given App Template revision. You can add tags using the ArconQ CLI when uploading your App Template. For more details, see the App Template tags documentation.

Q: Where can I see the tags for my App Template revisions?
A: You can review tags in the details view of a given App Template. For Apps using a revision with tags, they will be displayed in the Apps tiles and list views, as well as in the details of your App. Check the Tags on ArconQ's UI section for more information.

Managing App Templates​

Q: How can I browse and create App Templates in ArconQ?
A: To browse App Templates, go to the ArconQ UI, click on "App Templates" under "REPOSITORY" in the sidebar. To create a new App Template, click on "CREATE APP TEMPLATE" and follow the wizard. For detailed instructions, see the Managing App Templates guide.

Q: How can I edit or delete an existing App Template?
A: To edit an App Template, open the App Template Manager, where you can modify common settings or create a new revision to change files, startup commands, and settings. To delete an App Template, first stop and delete all Apps using it, then click "DELETE" in the Common section of the App Template Manager. For more information, check the Viewing and editing App Templates section.

Uploading App Templates​

Q: How can I upload an App Template to ArconQ?
A: There are two main methods to upload an App Template:

  1. Using the Graphical UI:
    • Navigate to the App Templates section in the ArconQ UI.
    • Click "CREATE APP TEMPLATE" and follow the wizard.
    • Upload your app files archive, specify startup settings, and configure your app.
  2. Using the ArconQ CLI:
    • Use the arq push command to automate the upload process.

Deleting Unused App Template Revisions​

Q: How can I delete unused App Template revisions in ArconQ?
A: ArconQ offers a purge feature to remove obsolete and unused revisions. To use this feature:

  1. Log in with administrative privileges.
  2. Navigate to the Maintenance tab in the left navigation menu.
  3. Look for the "Purge unused revisions" option.
  4. Click on "PERFORM MAINTENANCE" to initiate the purge.
  5. Confirm the action in the dialog box that appears.

Q: Are there any safety measures to prevent deleting necessary revisions?
A: Yes, the system will not purge revisions that:

  • Are the only version for an App Template.
  • Are newer than any version currently used by the active application.
  • Are in use by an application at the moment.

Role Management​

Q: How can I create and manage roles in ArconQ?
A: As an administrator, you can create, edit, and delete roles in the Roles view of the admin panel. To create a new role, navigate to the Roles view and click on "CREATE APP TEMPLATE". To edit or delete a role, use the respective options in the Roles view. For more details, see the Role management guide.

Q: What happens when I delete a role?
A: When you delete a role, it is removed from all users and External Clients who were assigned that role. This action cannot be undone, so use caution when deleting roles. For more information, check the Impact of role deletion section.

ArconQ Store​

Q: How can I add a Store connection to an existing ArconQ instance?
A: As an administrator, you can add a store link through the admin area. Navigate to the 'Store Connections' section, click 'Create Store', and fill in the required fields including Store Name, Store URL, Client ID, and Client Secret. For step-by-step instructions, see the How to Add a Store connection guide.

Metrics and Monitoring​

Advanced Logs Match​

Q: How can I perform exact match searches in ArconQ logs?
A: ArconQ provides an "Exact Match" feature for precise log searches. To use it, enter your search term in the Logs tab search bar and check the "Exact Match" checkbox. This will restrict results to only those that match your query string exactly. For more information, see the Advanced logs match documentation.

Q: What's the difference between exact match and regular search in ArconQ logs?
A: Regular search uses fuzzy matching to find terms similar to your query, while exact match only returns results that precisely match your search term. You can toggle between these modes by checking or unchecking the "Exact Match" checkbox in the Logs tab. This allows you to choose between strict accuracy and more flexible search results based on your needs. Check the Examples section in the documentation for visual comparisons.

Metrics and Grafana Dashboards​

Q: How do I enable metrics during ArconQ installation?
A: To enable metrics, modify the metrics.enabled flag within the ArconQ Helm chart to true. For example:

helm install 'arconq-prod' arconq/arconq --version '1.0.7' --namespace 'arq-prod' --set 'metrics.enabled=true'

Q: How do I access Grafana dashboards in ArconQ?
A: There are two ways to access Grafana dashboards:

  1. Directly within ArconQ's UI in the Metrics view.
  2. By accessing Grafana directly via the ArconQ URL with the /grafana suffix. For example, if ArconQ is hosted at https://arconq.prod, Grafana can be reached at https://arconq.prod/grafana.

Message Broker​

Q: Where can I find the credentials for the Message Broker?
A: The credentials (Username and Password) for the Message Broker can be found in the configuration window that appears when you click on the 'Message Broker' tile in the 'Integrations' page.