Instantiation Service

The Instantiation Service is VS Code’s dependency injection (DI) framework. It manages service lifetimes, resolves dependencies automatically, and provides a clean way to access platform services throughout the codebase.

Overview

VS Code uses constructor-based dependency injection with decorators to declare service dependencies. The Instantiation Service creates instances with all their dependencies automatically resolved.

Core Concepts

Service Identifiers

Services are identified by unique ServiceIdentifier tokens created with createDecorator:

import { createDecorator } from 'vs/platform/instantiation/common/instantiation';

export interface IMyService {
  readonly _serviceBrand: undefined;
  
  doSomething(): void;
}

export const IMyService = createDecorator<IMyService>('myService');

Service Brand: The _serviceBrand property is a TypeScript trick that ensures type safety. It’s never actually used at runtime but prevents accidental type mismatches.

Service Implementation

Implement services as classes and declare dependencies using parameter decorators:

import { IInstantiationService } from 'vs/platform/instantiation/common/instantiation';
import { IWorkspaceContextService } from 'vs/platform/workspace/common/workspace';
import { IConfigurationService } from 'vs/platform/configuration/common/configuration';

export class MyService implements IMyService {
  declare readonly _serviceBrand: undefined;

  constructor(
    @IWorkspaceContextService private readonly workspaceService: IWorkspaceContextService,
    @IConfigurationService private readonly configService: IConfigurationService
  ) {
    // Dependencies are automatically injected
  }

  doSomething(): void {
    const config = this.configService.getValue('myExtension.setting');
    const workspace = this.workspaceService.getWorkspace();
    // Use the services...
  }
}

Registering Services

import { InstantiationService } from 'vs/platform/instantiation/common/instantiationService';
import { ServiceCollection } from 'vs/platform/instantiation/common/serviceCollection';
import { SyncDescriptor } from 'vs/platform/instantiation/common/descriptors';

const services = new ServiceCollection();

// Register with an instance
services.set(IMyService, new MyService(...));

// Or register with a descriptor (lazy instantiation)
services.set(IMyService, new SyncDescriptor(MyService));

const instantiationService = new InstantiationService(services);

The IInstantiationService Interface

export interface IInstantiationService {
  readonly _serviceBrand: undefined;

  /**
   * Synchronously creates an instance that is denoted by the descriptor
   */
  createInstance<T>(descriptor: SyncDescriptor0<T>): T;
  createInstance<Ctor extends new (...args: any[]) => unknown, R extends InstanceType<Ctor>>(
    ctor: Ctor, 
    ...args: GetLeadingNonServiceArgs<ConstructorParameters<Ctor>>
  ): R;

  /**
   * Calls a function with a service accessor.
   */
  invokeFunction<R, TS extends any[] = []>(
    fn: (accessor: ServicesAccessor, ...args: TS) => R, 
    ...args: TS
  ): R;

  /**
   * Creates a child of this service which inherits all current services
   * and adds/overwrites the given services.
   */
  createChild(services: ServiceCollection, store?: DisposableStore): IInstantiationService;

  /**
   * Disposes this instantiation service.
   */
  dispose(): void;
}

Common Usage Patterns

Creating Instances with Dependencies

Use createInstance() to instantiate classes with automatic dependency resolution:

// In a class that receives IInstantiationService
class MyController {
  constructor(
    @IInstantiationService private readonly instantiationService: IInstantiationService
  ) {}

  createWidget(): MyWidget {
    // MyWidget's dependencies will be automatically injected
    return this.instantiationService.createInstance(MyWidget);
  }
}

You can also pass additional static arguments:

class MyWidget {
  constructor(
    private readonly id: string,  // Static argument
    private readonly name: string,  // Static argument
    @IConfigurationService private readonly configService: IConfigurationService  // Injected
  ) {}
}

// Create with static args
const widget = this.instantiationService.createInstance(MyWidget, 'widget-1', 'My Widget');

Using invokeFunction for Service Access

invokeFunction() lets you access services without creating a class:

this.instantiationService.invokeFunction((accessor) => {
  const configService = accessor.get(IConfigurationService);
  const workspaceService = accessor.get(IWorkspaceContextService);
  
  const config = configService.getValue('myExtension.setting');
  const workspace = workspaceService.getWorkspace();
  
  // Do something with the services...
});

This is useful for one-off operations or when you need services in a function rather than a class.

Creating Child Instantiation Services

Child services inherit parent services but can override specific ones:

const childServices = new ServiceCollection();
childServices.set(IMyService, new TestMyService());  // Override for testing

const childInstantiationService = parentInstantiationService.createChild(childServices);

// Instances created by child will use TestMyService
const instance = childInstantiationService.createInstance(MyComponent);

This is commonly used for:

Testing (mocking services)
Scoped services (window-specific, editor-specific)
Isolated contexts

Service Descriptors

SyncDescriptor enables lazy service instantiation:

import { SyncDescriptor } from 'vs/platform/instantiation/common/descriptors';

export class SyncDescriptor<T> {
  readonly ctor: any;
  readonly staticArguments: unknown[];
  readonly supportsDelayedInstantiation: boolean;

  constructor(
    ctor: new (...args: any[]) => T, 
    staticArguments: unknown[] = [], 
    supportsDelayedInstantiation: boolean = false
  ) {
    this.ctor = ctor;
    this.staticArguments = staticArguments;
    this.supportsDelayedInstantiation = supportsDelayedInstantiation;
  }
}

Benefits of using descriptors:

Services are only created when first accessed
Reduces startup time
Enables cyclic dependency resolution
Supports delayed instantiation via proxies

Advanced Features

Cyclic Dependency Detection

The Instantiation Service detects and reports cyclic dependencies:

// This will throw a CyclicDependencyError
class ServiceA {
  constructor(@IServiceB serviceB: IServiceB) {}
}

class ServiceB {
  constructor(@IServiceA serviceA: IServiceA) {}
}

The error message includes a graph showing the dependency cycle.

Delayed Instantiation

Services can opt into delayed instantiation using proxies:

services.set(IMyService, new SyncDescriptor(
  MyService, 
  [], 
  true  // supportsDelayedInstantiation
));

With delayed instantiation:

A proxy is returned immediately
The real service is created during idle time or on first property access
Event subscriptions work correctly before instantiation
Improves startup performance for heavy services

Service Collection

import { ServiceCollection } from 'vs/platform/instantiation/common/serviceCollection';

export class ServiceCollection {
  constructor(...entries: [ServiceIdentifier<any>, any][]) {
    // Initialize with entries
  }

  set<T>(id: ServiceIdentifier<T>, instanceOrDescriptor: T | SyncDescriptor<T>): T | SyncDescriptor<T>;
  has(id: ServiceIdentifier<any>): boolean;
  get<T>(id: ServiceIdentifier<T>): T | SyncDescriptor<T>;
}

Real-World Example

Here’s how the Editor service is typically structured:

// Define the service interface
export const ICodeEditorService = createDecorator<ICodeEditorService>('codeEditorService');

export interface ICodeEditorService {
  readonly _serviceBrand: undefined;
  
  getActiveCodeEditor(): ICodeEditor | null;
  listCodeEditors(): ICodeEditor[];
  registerDecorationType(key: string, options: IDecorationRenderOptions): void;
}

// Implement the service
export class CodeEditorService implements ICodeEditorService {
  declare readonly _serviceBrand: undefined;

  private readonly _editors = new Map<string, ICodeEditor>();

  constructor(
    @IThemeService private readonly themeService: IThemeService,
    @IConfigurationService private readonly configService: IConfigurationService
  ) {
    // Setup...
  }

  getActiveCodeEditor(): ICodeEditor | null {
    // Implementation...
  }

  listCodeEditors(): ICodeEditor[] {
    return Array.from(this._editors.values());
  }

  registerDecorationType(key: string, options: IDecorationRenderOptions): void {
    // Use theme service and config service
    const theme = this.themeService.getColorTheme();
    // ...
  }
}

Best Practices

Always use interfaces: Define service interfaces separately from implementations. This enables testing with mock implementations.

One service identifier per service: Each service should have exactly one ServiceIdentifier. Don’t create multiple identifiers for the same service.

Minimize constructor logic: Keep constructor logic minimal. Use initialization methods or lifecycle hooks for complex setup.

Dispose resources: If your service holds resources (subscriptions, file handles), implement IDisposable and clean up in dispose().

Testing with Dependency Injection

The DI system makes testing easy:

import { TestInstantiationService } from 'vs/platform/instantiation/test/common/instantiationServiceMock';

suite('MyService', () => {
  let instantiationService: TestInstantiationService;
  let myService: MyService;

  setup(() => {
    instantiationService = new TestInstantiationService();
    
    // Mock dependencies
    instantiationService.stub(IConfigurationService, new MockConfigurationService());
    instantiationService.stub(IWorkspaceContextService, new MockWorkspaceService());
    
    myService = instantiationService.createInstance(MyService);
  });

  test('should do something', () => {
    myService.doSomething();
    // Assert...
  });
});

Extension API

Core Services

Platform APIs

Overview

Core Concepts

Service Identifiers

Service Implementation

Registering Services

The IInstantiationService Interface

Common Usage Patterns

Service Descriptors

Advanced Features

Cyclic Dependency Detection

Delayed Instantiation

Service Collection

Real-World Example

Best Practices

Testing with Dependency Injection

See Also

​Overview

​Core Concepts

​Service Identifiers

​Service Implementation

​Registering Services

​The IInstantiationService Interface

​Common Usage Patterns

​Service Descriptors

​Advanced Features

​Cyclic Dependency Detection

​Delayed Instantiation

​Service Collection

​Real-World Example

​Best Practices

​Testing with Dependency Injection

​See Also

Overview

Core Concepts

Service Identifiers

Service Implementation

Registering Services

The IInstantiationService Interface

Common Usage Patterns

Service Descriptors

Advanced Features

Cyclic Dependency Detection

Delayed Instantiation

Service Collection

Real-World Example

Best Practices

Testing with Dependency Injection

See Also