Version
Google Translate
Contributors Edit (4/13/2025)
Avatar

VCP Application Startup

You typically use the VCP CLI's vcp new command to get started with one of the pre-built startup solution templates. When you do that, you generally don't need to know the details of how the VCP is integrated with your application or how it is configured and initialized. The startup template also comes with the fundamental VCP packages and application modules are pre-installed and configured for you.

It is always suggested to get started with a startup template and modify it for your requirements. Read this document only if you want to understand the details or if you need to modify how the VCP starts.

While the VCP has a lot of features and integrations, it is built as a lightweight and modular framework. It consists of hundreds of NuGet and NPM packages, so you can only use the features you need. If you follow the Getting Started with an Empty ASP.NET Core MVC / Razor Pages Application document, you'll see how easy it is to install the VCP into an empty ASP.NET Core project from scratch. You only need to install a single NuGet package and make a few small changes.

This document is for who wants to better understand how the VCP is initialized and configured on startup.

Installing to a Console Application

A .NET Console application is the minimalist .NET application. So, it is best to show the installing of the VCP to a console application as a minimalist example.

If you create a new console application with Visual Studio (for .NET 8.0 or later), you will see the following solution structure (I named the solution as MyConsoleDemo):

app-startup-console-initial

This example uses the top level statements, so it consists of only a single line of code.

The first step is to install the Verto.Vcp.Core NuGet package, which is the most core NuGet package of the VCP. You can install it using the VCP CLI. Execute the following command in the folder of the .csproj file that you want to install the package on:

vcp add-package Verto.Vcp.Core

If you haven't done it yet, you first need to install the VCP CLI. For other installation options, see the package description page.

Alternatively, you can use a command-line terminal in the root folder of the project (the folder containing the MyConsoleDemo.csproj file, for this example):

dotnet add package Verto.Vcp.Core

After adding the NuGet package, we should create a root module class for our application. We can create the following class in the project:

using Verto.Vcp.Modularity;

namespace MyConsoleDemo
{
    public class MyConsoleDemoModule : VcpModule
    {
    }
}

This is an empty class deriving from the VcpModule class. It is the main class that you will control your application's dependencies with, and implement your configuration and startup/shutdown logic. For more information, please check the Modularity document.

As the second and the last step, change the Program.cs as shown in the following code block:

using MyConsoleDemo;
using Verto.Vcp;

// 1: Create the VCP application container
using var application = await VcpApplicationFactory.CreateAsync<MyConsoleDemoModule>();

// 2: Initialize/start the VCP (and all the modules)
await application.InitializeAsync();

Console.WriteLine("VCP has been started...");

// 3: Stop the VCP (and all the modules)
await application.ShutdownAsync();

That's all. Now, VCP is installed, integrated, started and stopped in your application. From now, you can install VCP packages to your application whenever you need them.

Installing a Framework Package

If you want to send emails from your .NET application, you can use .NET's standard SmtpClient class. VCP also provides an IEmailSender service that simplifies sending emails and configuring the email settings in a central place. If you want to use it, you should install the Verto.Vcp.Emailing NuGet package to your project:

dotnet add package Verto.Vcp.Emailing

Once you add a new VCP package/module, you also need to specify the module dependency from your module class. So, change the MyConsoleDemoModule class as shown below:

using Verto.Vcp.Emailing;
using Verto.Vcp.Modularity;

namespace MyConsoleDemo
{
    [DependsOn(typeof(VcpEmailingModule))] // Added the module dependency
    public class MyConsoleDemoModule : VcpModule
    {
    }
}

I've just added a [DependsOn] attribute to declare that I want to use the VCP Emailing Module (VcpEmailingModule). Now, I can use the IEmailSender service in my Program.cs:

using Microsoft.Extensions.DependencyInjection;
using MyConsoleDemo;
using Verto.Vcp;
using Verto.Vcp.Emailing;

using var application = await VcpApplicationFactory.CreateAsync<MyConsoleDemoModule>();
await application.InitializeAsync();

// Sending emails using the IEmailSender service
var emailsender = application.ServiceProvider.GetRequiredService<IEmailSender>();
await emailsender.SendAsync(
    to: "info@acme.com",
    subject: "Hello World",
    body: "My message body..."
);

await application.ShutdownAsync();

If you run that application, you get a runtime error indicating that the email sending settings haven't been done yet. You can check the Email Sending document to learn how to configure it.

That's all. Install an VCP NuGet package, add the module dependency (using the [DependsOn] attribute) and use any service inside the NuGet package.

The VCP CLI already has a special command to perform the addition of an VCP NuGet and also adding the [DependsOn] attribute to your module class for you with a single command:

vcp add-package Verto.Vcp.Emailing

We suggest you to use the vcp add-package command instead of manually doing it.

VcpApplicationFactory

VcpApplicationFactory is the main class that creates an VCP application container. It provides a single static CreateAsync (and Create if you can't use asynchronous programming) method with multiple overloads. Let's investigate these overloads to understand where you can use them.

The first overload gets a generic module class parameter as we've used before in this document:

VcpApplicationFactory.CreateAsync<MyConsoleDemoModule>();

The generic class parameter should be the root module class of your application. All the other modules are resolved as dependencies of that module.

The second overload gets the module class as a Type parameter, instead of the generic parameter. So, the previous code block could be re-written as shown below:

VcpApplicationFactory.CreateAsync(typeof(MyConsoleDemoModule));

Both overloads work exactly the same. So, you can use the second one if you don't know the module class type on development time and you (somehow) calculate it on runtime.

If you use one of the methods above, VCP creates an internal service collection (IServiceCollection) and an internal service provider (IServiceProvider) to setup the dependency injection system internally. Notice that we've used the application.ServiceProvider property in the Installing a Framework Package section to resolve the IEmailSender service from the dependency injection system.

The next overload gets an IServiceCollection parameter from you to allow you to setup the dependency injection system yourself, or integrate to another framework (like ASP.NET Core) that also sets up the dependency injection system internally.

We can change the Program.cs as shown below to externally manage the dependency injection setup:

using Microsoft.Extensions.DependencyInjection;
using MyConsoleDemo;
using Verto.Vcp;

// 1: Manually created the IServiceCollection
IServiceCollection services = new ServiceCollection();

// 2: Pass the IServiceCollection externally to the VCP
using var application = await VcpApplicationFactory
    .CreateAsync<MyConsoleDemoModule>(services);

// 3: Manually built the IServiceProvider object
IServiceProvider serviceProvider = services.BuildServiceProvider();

// 4: Pass the IServiceProvider externally to the VCP
await application.InitializeAsync(serviceProvider);

Console.WriteLine("VCP has been started...");

await application.ShutdownAsync();

In this example, we've used .NET's standard dependency injection container. The services.BuildServiceProvider() call creates the standard container. However, VCP provides an alternative extension method, BuildServiceProviderFromFactory(), that properly works even if you are using another dependency injection container:

IServiceProvider serviceProvider = services.BuildServiceProviderFromFactory();

You can check the Autofac Integration document if you want to learn how you can integrate the Autofac dependency injection container with the VCP.

Finally, the CreateAsync method has a last overload that takes the module class name as a Type parameter and a IServiceCollection object. So, we could re-write the last CreateAsync method usage as in the following code block:

using var application = await VcpApplicationFactory
    .CreateAsync(typeof(MyConsoleDemoModule), services);

All of the CreateAsync method overloads have Create counterparts. If your application type can not utilize asynchronous programming (that means you can't use the await keyword), then you can use the Create method instead of the CreateAsync method.

VcpApplicationCreationOptions

All of the CreateAsync overloads can get an optional Action<VcpApplicationCreationOptions> parameter to configure the options that are used on the application creation. See the following example:

using var application = await VcpApplicationFactory
    .CreateAsync<MyConsoleDemoModule>(options =>
    {
        options.ApplicationName = "MyApp";
    });

We've passed a lambda method to configure the ApplicationName option. Here's a list of all standard options:

  • ApplicationName: A human-readable name for the application. It is a unique value for an application.
  • Configuration: Can be used to setup the application configuration when it is not provided by the hosting system. It is not needed for ASP.NET Core and other .NET hosted applications. However, if you've used VcpApplicationFactory with an internal service provider, you can use this option to configure how the application configuration is built.
  • Environment: Environment name for the application.
  • PlugInSources: A list of plugin sources. See the Plug-In Modules documentation to learn how to work with plugins.
  • Services: The IServiceCollection object that can be used to register service dependencies. You generally don't need that, because you configure your services in your module class. However, it can be used while writing extension methods for the VcpApplicationCreationOptions class.

The ApplicationName option

As defined above, the ApplicationName option is a human-readable name for the application. It is a unique value for an application.

ApplicationName is used by the VCP in several places to distinguish the application. For example, the audit logging system saves the ApplicationName in each audit log record written by the related application, so you can understand which application has created the audit log entry. So, if your system consists of multiple applications (like a microservice solution) that are saving audit logs to a single point, you should be sure that each application has a different ApplicationName.

The ApplicationName property's value is set automatically from the entry assembly's name (generally, the project name in a .NET solution) by default, which is proper for most cases, since each application typically has a unique entry assembly name.

There are two ways to set the application name to a different value. In this first approach, you can set the ApplicationName property in your application's configuration. The easiest way is to add an ApplicationName field to your appsettings.json file:

{
    "ApplicationName": "Services.Ordering"
}

Alternatively, you can set VcpApplicationCreationOptions.ApplicationName while creating the VCP application. You can find the AddApplication or AddApplicationAsync call in your solution (typically in the Program.cs file), and set the ApplicationName option as shown below:

await builder.AddApplicationAsync<OrderingServiceHttpApiHostModule>(options =>
{
    options.ApplicationName = "Services.Ordering";
});

IApplicationInfoAccessor

If you need to access the ApplicationName later in your solution, you can inject the IApplicationInfoAccessor service and get the value from its ApplicationName property.

IApplicationInfoAccessor also provides an InstanceId value, that is a random GUID value that is generated when your application starts. You can use that value to distinguish application instances from each other.

IVcpApplication

VcpApplicationFactory returns an IVcpApplication object from its CreateAsync (or Create) method. IVcpApplication is the main container for an VCP application. It is also registered to the dependency injection system, so you can inject IVcpApplication in your services to use its properties and methods.

Here's a list of IVcpApplication properties you may want to know:

  • StartupModuleType: Gets the root module of the application that was used while creating the application container (on the VcpApplicationFactory.CreateAsync method).
  • Services: A list of all service registrations (the IServiceCollection object). You can not add new services to this collection after application initialization (you can actually add, but it won't have any effect).
  • ServiceProvider: A reference to the root service provider used by the application. This can not be used before initializing the application. If you need to resolve non-singleton services from that IServiceProvider object, always create a new service scope and dispose it after usage. Otherwise, your application will have memory leak problems. See the Releasing/Disposing Services section of the dependency injection document for more information about service scopes.
  • Modules: A read-only list of all the modules loaded into the current application. Alternatively, you can inject the IModuleContainer service if you need to access the module list in your application code.

The IVcpApplication interface extends the IApplicationInfoAccessor interface, so you can get the ApplicationName and InstanceId values from it. However, if you only need to access these properties, inject and use the IApplicationInfoAccessor service instead.

IVcpApplication is disposable. Always dispose of it before exiting your application.

IVcpHostEnvironment

Sometimes, while creating an application, we need to get the current hosting environment and take actions according to that. In such cases, we can use some services such as IWebHostEnvironment or IWebAssemblyHostEnvironment provided by .NET, in the final application.

However, we can not use these services in a class library, which is used by the final application. VCP provides the IVcpHostEnvironment service, which allows you to get the current environment name whenever you want. IVcpHostEnvironment is used by the VCP in several places to perform specific actions by the environment. For example, VCP reduces the cache duration on the Development environment for some services.

IVcpHostEnvironment obtains the current environment name by the following order:

  1. Gets and sets the environment name if it's specified in the VcpApplicationCreationOptions.
  2. Tries to obtain the environment name from the IWebHostEnvironment or IWebAssemblyHostEnvironment services for ASP.NET Core & Blazor WASM applications if the environment name isn't specified in the VcpApplicationCreationOptions.
  3. Sets the environment name as Production, if the environment name is not specified or can not be obtained from the services.

You can configure the VcpApplicationCreationOptions options class while creating the VCP application and set an environment name to its Environment property. You can find the AddApplication or AddApplicationAsync call in your solution (typically in the Program.cs file), and set the Environment option as shown below:

await builder.AddApplicationAsync<OrderingServiceHttpApiHostModule>(options =>
{
    options.Environment = Environments.Staging; //or directly set as "Staging"
});

Then, whenever you need to get the current environment name or check the environment, you can use the IVcpHostEnvironment interface:

public class MyDemoService
{
    private readonly IVcpHostEnvironment _vcpHostEnvironment;
    
    public MyDemoService(IVcpHostEnvironment vcpHostEnvironment)
    {
        _vcpHostEnvironment = vcpHostEnvironment;
    }

    public void MyMethod()
    {
        var environmentName = _vcpHostEnvironment.EnvironmentName;

        if (_vcpHostEnvironment.IsDevelopment()) { /* ... */ } 

        if (_vcpHostEnvironment.IsStaging()) { /* ... */ }

        if (_vcpHostEnvironment.IsProduction()) { /* ... */ }

        if (_vcpHostEnvironment.IsEnvironment("custom-environment")) { /* ... */ }
    }
}

.NET Generic Host & ASP.NET Core Integrations

VcpApplicationFactory can create a standalone VCP application container without any external dependency. However, in most cases, you will want to integrate it with .NET's generic host or ASP.NET Core. For such usages, VCP provides built-in extension methods to easily create an VCP application container that is well-integrated to these systems.

The Getting Started with an Empty ASP.NET Core MVC / Razor Pages Application document clearly explains how you can create an VCP application container in an ASP.NET Core application.

You can also create a console application to see how it is integrated with .NET Generic Host.

Most of the times, you will directly create VCP applications using the VCP CLI's new command. So, you don't need to care about these integration details.

See Also

In this document