Skip to content

.NET Agent: Manage metadata and tags🔗

The Lightrun .NET agent allows you to attach metadata—such as a display name and tags—to each running agent instance for identification and targeting purposes. Metadata and tags help you locate agents more easily and group them for bulk actions across multiple applications and environments. For more information on Lightrun tags, see Lightrun tags overview.

Agent metadata🔗

The Lightrun .NET agent supports two metadata properties:

  • DisplayName: Identifies the application instance (for example, server name, company site).
  • Tags: User-defined labels that group agents by deployment context (for example, production, staging, QA).

Metadata is loaded when the agent starts and remains fixed for the lifetime of the process.

Methods for adding metadata🔗

Define agent metadata using one of the following methods:

  • Programmatically when calling LightrunAgent.Start.
  • Via an agent.metadata.json file.

Add agent metadata within the code🔗

The metadata properties can be declared in the LightrunAgent.Start command, as follows: 

LightrunAgent.Start(new AgentOptions {
    Secret = "<LIGHTRUN_SECRET>",
    DisplayName = "<agent_display_name>",
    Tags = new[] {"Production", "Main", "EastUS"}
});

Add agent metadata to an agent.metadata.json file🔗

  1. Create an agent.metadata.json file in your project’s repository.
  2. Insert your tag and display name into the agent.metadata.json file in the following format: 
    {
    "registration": {
        "displayName": "<DISPLAY_NAME>",
        "tags": [
            {
                "name": "<Tag1>"
            },
            {
                "name": "<Tag2>"
            },
            {
                "name": "<Tag3>"
            }
        ]
    }
}
  3. Add the path to the agent.metadata.json file to your LightrunAgent.Start command.
    LightrunAgent.Start(new AgentOptions {
    Secret = "<LIGHTRUN_SECRET>",
    RegistrationMetadataFile = "<full-path-to-agent.metadata.json-file>"
});

Tag management🔗

Once tags are defined and associated with agents, you can manage and monitor them from the Lightrun plugins and Lightrun Management Portal.

Manage unused tags🔗

You can manually delete unused tags from the Lightrun plugin UI or from the Lightrun Management Portal.

A tag cannot be deleted if it is currently associated with an agent or an action.

Starting with version 1.74, the Auto-cleanup unused tags parameter was introduced and is enabled by default. When enabled, unused tags are automatically removed after 1 day to keep the tags list clean in large deployments. Tags are automatically regenerated when the agents reconnect.

Modify the cleanup interval🔗

You can modify the cleanup interval or disable the parameter.

  1. Log in to the Lightrun Management Portal.
  2. Navigate to Settings → Compliance → Service Configuration.
  3. Under Other, adjust the Auto-cleanup unused tags interval (for example, 1 week), or disable the feature.
  4. Click Save Changes.

View tag details in the Management Portal🔗

  1. Log in to your Lightrun Management Portal.

  2. Navigate to Entities > Tags.

    Manage tags

    The Tags page displays the following information:

    Parameter Description
    Name Tag name
    Actions Actions currently attached to the tag
    Agent Number Number of agents associated with the tag
Last update: December 25, 2025