Angular Dependency Injection
Dependency Injection (DI) is a way to create objects that depend upon other objects. A Dependency Injection system supplies the dependent objects (called the dependencies) when it creates an instance of an object.
The Dependency Injection pattern page describes this general approach. The guide you're reading nowexplains how Angular's own Dependency Injection system works.
DI by example
You'll learn Angular Dependency Injection through a discussion of the sample app that accompanies this guide. Run the live example / download example anytime.
Start by reviewing this simplified version of the heroes feature from the The Tour of Heroes.
The
HeroesComponent
is the top-level heroes component. It's only purpose is to display the HeroListComponent
which displays a list of hero names.
This version of the
HeroListComponent
gets its heroes
from the HEROES
array, an in-memory collection defined in a separate mock-heroes
file.export class HeroListComponent {
heroes = HEROES;
}
That may suffice in the early stages of development, but it's far from ideal. As soon as you try to test this component or get heroes from a remote server, you'll have to change the implementation of
HerosListComponent
and replace every other use of the HEROES
mock data.
It's better to hide these details inside a service class, defined in its own file.
Create an injectable HeroService
The Angular CLI can generate a new
HeroService
class in the src/app/heroes
folder with this command.ng generate service heroes/hero
The command above creates the following
HeroService
skeleton.import { Injectable } from '@angular/core';
@Injectable({
providedIn: 'root',
})
export class HeroService {
constructor() { }
}
The
@Injectable
decorator is an essential ingredient in every Angular service definition. The rest of the class has been rewritten to expose a getHeroes
method that returns the same mock data as before.
- import { Injectable } from '@angular/core';
- import { HEROES } from './mock-heroes';
-
- @Injectable({
- // we declare that this service should be created
- // by the root application injector.
-
- providedIn: 'root',
- })
- export class HeroService {
- getHeroes() { return HEROES; }
- }
Of course, this isn't a real data service. If the app were actually getting data from a remote server, the
getHeroes
method signature would have to be asynchronous.
That's a defect we can safely ignore in this guide where our focus is on injecting the service into the
HeroList
component.Injectors
A service like
HeroService
is just a class in Angular until you register it with an Angular dependency injector.
An Angular injector is responsible for creating service instances and injecting them into classes like the
HeroListComponent
.
You rarely create an Angular injector yourself. Angular creates injectors for you as it executes the app, starting with the root injector that it creates during the bootstrap process.
Angular doesn't automatically know how you want to create instances of your services or the injector to create your service. You must configure it by specifying providers for every service.
Providers tell the injector how to create the service. Without a provider, the injector would not know that it is responsible for injecting the service nor be able to create the service.
You'll learn much more about providers below. For now, it is sufficient to know that they configure where and how services are created.
There are many ways to register a service provider with an injector. This section shows the most common ways of configuring a provider for your services.
@Injectable providers
The
@Injectable
decorator identifies services and other classes that are intended to be injected. It can also be used to configure a provider for those services.
Here we configure a provider for
HeroService
using the @Injectable
decorator on the class.import { Injectable } from '@angular/core';
@Injectable({
providedIn: 'root',
})
export class HeroService {
constructor() { }
}
providedIn
tells Angular that the root injector is responsible for creating an instance of the HeroService
(by invoking its constructor) and making it available across the application. The CLI sets up this kind of a provider automatically for you when generating a new service.
Sometimes it's not desirable to have a service always be provided in the application root injector. Perhaps users should explicitly opt-in to using the service, or the service should be provided in a lazily-loaded context. In this case, the provider should be associated with a specific
@NgModule
class, and will be used by whichever injector includes that module.
In the following excerpt, the
@Injectable
decorator is used to configure a provider that will be available in any injector that includes the HeroModule.import { Injectable } from '@angular/core';
import { HeroModule } from './hero.module';
import { HEROES } from './mock-heroes';
@Injectable({
// we declare that this service should be created
// by any injector that includes HeroModule.
providedIn: HeroModule,
})
export class HeroService {
getHeroes() { return HEROES; }
}
@NgModule providers
In the following excerpt, the root
AppModule
registers two providers in its providers
array.providers: [
UserService,
{ provide: APP_CONFIG, useValue: HERO_DI_CONFIG }
],
The first entry registers the
UserService
class (not shown) under the UserService
injection token. The second registers a value (HERO_DI_CONFIG
) under the APP_CONFIG
injection token.
With the above registrations, Angular can inject the
UserService
or the HERO_DI_CONFIG
value into any class that it creates.
You'll learn about injection tokens and provider syntax below.
@Component providers
In addition to providing the service application-wide or within a particular
@NgModule
, services can also be provided in specific components. Services provided in component-level is only available within that component injector or in any of its child components.
The example below shows a revised
HeroesComponent
that registers the HeroService
in its providers
array.import { Component } from '@angular/core';
import { HeroService } from './hero.service';
@Component({
selector: 'app-heroes',
providers: [ HeroService ],
template: `
Heroes
`
})
export class HeroesComponent { }
@Injectable, @NgModule or @Component?
Should you provide a service with an
@Injectable
decorator, in an @NgModule
, or within an @Component
? The choices lead to differences in the final bundle size, service scope, and service lifetime.
When you register providers in the @Injectable decorator of the service itself, optimization tools such as those used by the CLI's production builds can perform tree shaking, which removes services that aren't used by your app. Tree shaking results in smaller bundle sizes.
Angular module providers (
@NgModule.providers
) are registered with the application's root injector. Angular can inject the corresponding services in any class it creates. Once created, a service instance lives for the life of the app and Angular injects this one service instance in every class that needs it.
You're likely to inject the
UserService
in many places throughout the app and will want to inject the same service instance every time. Providing the UserService
with an Angular module is a good choice if an @Injectable
provider is not an option..
To be precise, Angular module providers are registered with the root injector unless the module islazy loaded. In this sample, all modules are eagerly loaded when the application starts, so all module providers are registered with the app's root injector.
A component's providers (
@Component.providers
) are registered with each component instance's own injector.
Angular can only inject the corresponding services in that component instance or one of its descendant component instances. Angular cannot inject the same service instance anywhere else.
Note that a component-provided service may have a limited lifetime. Each new instance of the component gets its own instance of the service and, when the component instance is destroyed, so is that service instance.
In this sample app, the
HeroComponent
is created when the application starts and is never destroyed so the HeroService
created for the HeroComponent
also live for the life of the app.
If you want to restrict
HeroService
access to the HeroComponent
and its nested HeroListComponent
, providing the HeroService
in the HeroComponent
may be a good choice.
The scope and lifetime of component-provided services is a consequence of the way Angular creates component instances.
Providers
A service provider provides the concrete, runtime version of a dependency value. The injector relies on providers to create instances of the services that the injector injects into components, directives, pipes, and other services.
You must register a service provider with an injector, or it won't know how to create the service.
The next few sections explain the many ways you can specify a provider.
The class as its own provider
There are many ways to provide something that looks and behaves like a
Logger
. The Logger
class itself is an obvious and natural provider.providers: [Logger]
But it's not the only way.
You can configure the injector with alternative providers that can deliver an object that behaves like a
Logger
. You could provide a substitute class. You could provide a logger-like object. You could give it a provider that calls a logger factory function. Any of these approaches might be a good choice under the right circumstances.
What matters is that the injector has a provider to go to when it needs a
Logger
.The provide object literal
Here's the class-provider syntax again.
providers: [Logger]
This is actually a shorthand expression for a provider registration using a provider object literal with two properties:
[{ provide: Logger, useClass: Logger }]
The
provide
property holds the token that serves as the key for both locating a dependency value and registering the provider.
The second property is always a provider definition object, which you can think of as a recipe for creating the dependency value. There are many ways to create dependency values just as there are many ways to write a recipe.
Alternative class providers
Occasionally you'll ask a different class to provide the service. The following code tells the injector to return a
BetterLogger
when something asks for the Logger
.[{ provide: Logger, useClass: BetterLogger }]
Class provider with dependencies
Maybe an
EvenBetterLogger
could display the user name in the log message. This logger gets the user from the injected UserService
, which is also injected at the application level.@Injectable()
export class EvenBetterLogger extends Logger {
constructor(private userService: UserService) { super(); }
log(message: string) {
let name = this.userService.user.name;
super.log(`Message to ${name}: ${message}`);
}
}
Configure it like
BetterLogger
.[ UserService,
{ provide: Logger, useClass: EvenBetterLogger }]
Aliased class providers
Suppose an old component depends upon an
OldLogger
class. OldLogger
has the same interface as the NewLogger
, but for some reason you can't update the old component to use it.
When the old component logs a message with
OldLogger
, you'd like the singleton instance of NewLogger
to handle it instead.
The dependency injector should inject that singleton instance when a component asks for either the new or the old logger. The
OldLogger
should be an alias for NewLogger
.
You certainly do not want two different
NewLogger
instances in your app. Unfortunately, that's what you get if you try to alias OldLogger
to NewLogger
with useClass
.[ NewLogger,
// Not aliased! Creates two instances of `NewLogger`
{ provide: OldLogger, useClass: NewLogger}]
The solution: alias with the
useExisting
option.[ NewLogger,
// Alias OldLogger w/ reference to NewLogger
{ provide: OldLogger, useExisting: NewLogger}]
Value providers
Sometimes it's easier to provide a ready-made object rather than ask the injector to create it from a class.
// An object in the shape of the logger service
export function SilentLoggerFn() {}
const silentLogger = {
logs: ['Silent logger says "Shhhhh!". Provided via "useValue"'],
log: SilentLoggerFn
};
Then you register a provider with the
useValue
option, which makes this object play the logger role.[{ provide: Logger, useValue: silentLogger }]
Factory providers
Sometimes you need to create the dependent value dynamically, based on information you won't have until the last possible moment. Maybe the information changes repeatedly in the course of the browser session.
Suppose also that the injectable service has no independent access to the source of this information.
This situation calls for a factory provider.
To illustrate the point, add a new business requirement: the
HeroService
must hide secret heroes from normal users. Only authorized users should see secret heroes.
Like the
EvenBetterLogger
, the HeroService
needs a fact about the user. It needs to know if the user is authorized to see secret heroes. That authorization can change during the course of a single application session, as when you log in a different user.
Unlike
EvenBetterLogger
, you can't inject the UserService
into the HeroService
. The HeroService
won't have direct access to the user information to decide who is authorized and who is not.
Instead, the
HeroService
constructor takes a boolean flag to control display of secret heroes.constructor(
private logger: Logger,
private isAuthorized: boolean) { }
getHeroes() {
let auth = this.isAuthorized ? 'authorized ' : 'unauthorized';
this.logger.log(`Getting heroes for ${auth} user.`);
return HEROES.filter(hero => this.isAuthorized || !hero.isSecret);
}
You can inject the
Logger
, but you can't inject the boolean isAuthorized
. You'll have to take over the creation of new instances of this HeroService
with a factory provider.
A factory provider needs a factory function:
let heroServiceFactory = (logger: Logger, userService: UserService) => {
return new HeroService(logger, userService.user.isAuthorized);
};
Although the
HeroService
has no access to the UserService
, the factory function does.
You inject both the
Logger
and the UserService
into the factory provider and let the injector pass them along to the factory function:export let heroServiceProvider =
{ provide: HeroService,
useFactory: heroServiceFactory,
deps: [Logger, UserService]
};
The
useFactory
field tells Angular that the provider is a factory function whose implementation is the heroServiceFactory
.
The
deps
property is an array of provider tokens. The Logger
and UserService
classes serve as tokens for their own class providers. The injector resolves these tokens and injects the corresponding services into the matching factory function parameters.
Notice that you captured the factory provider in an exported variable,
heroServiceProvider
. This extra step makes the factory provider reusable. You can register the HeroService
with this variable wherever you need it.
In this sample, you need it only in the
HeroesComponent
, where it replaces the previous HeroService
registration in the metadata providers
array. Here you see the new and the old implementation side-by-side:Tree-shakable providers
Tree shaking is the ability to remove code that is not referenced in an application from the final bundle. Tree-shakable providers give Angular the ability to remove services that are not used in your application from the final output. This significantly reduces the size of your bundles.
Ideally, if an application is not injecting a service, it should not be included in the final output. However, it turns out that the Angular compiler cannot identify at build time if the service will be required or not. Because it's always possible to inject a service directly using
injector.get(Service)
, Angular cannot identify all of the places in your code where this injection could happen, so it has no choice but to include the service in the injector regardless. Thus, services provided in modules are not tree-shakeable.
Let us consider an example of non-tree-shakable providers in Angular.
In this example, to provide services in Angular, you include them in an
@NgModule
:import { Injectable, NgModule } from '@angular/core';
@Injectable()
export class Service {
doSomething(): void {
}
}
@NgModule({
providers: [Service],
})
export class ServiceModule {
}
This module can then be imported into your application module, to make the service available for injection in your app:
@NgModule({
imports: [
BrowserModule,
RouterModule.forRoot([]),
ServiceModule,
],
})
export class AppModule {
}
When
ngc
runs, it compiles AppModule into a module factory, which contains definitions for all the providers declared in all the modules it includes. At runtime, this factory becomes an injector that instantiates these services.
Tree-shaking doesn't work in the method above because Angular cannot decide to exclude one chunk of code (the provider definition for the service within the module factory) based on whether another chunk of code (the service class) is used. To make services tree-shakeable, the information about how to construct an instance of the service (the provider definition) needs to be a part of the service class itself.
Creating tree-shakable providers
To create providers that are tree-shakable, the information that used to be specified in the module should be specified in the
@Injectable
decorator on the service itself.
The following example shows the tree-shakeable equivalent to the
ServiceModule
example above:@Injectable({
providedIn: 'root',
})
export class Service {
}
In the example above,
providedIn
allows you to declare the injector which injects this service. Unless there is a special case, the value should always be root. Setting the value to root ensures that the service is scoped to the root injector, without naming a particular module that is present in that injector.
The service can be instantiated by configuring a factory function as shown below:
@Injectable({
providedIn: 'root',
useFactory: () => new Service('dependency'),
})
export class Service {
constructor(private dep: string) {
}
}
To override tree-shakable providers, register the provider using the
providers: []
array syntax of any Angular decorator that supports it.Inject a service
The
HeroListComponent
should get heroes from the HeroService
.
The component shouldn't create the
HeroService
with new
. It should ask for the HeroService
to be injected.
You can tell Angular to inject a dependency in the component's constructor by specifying a constructor parameter with the dependency type. Here's the
HeroListComponent
constructor, asking for the HeroService
to be injected.constructor(heroService: HeroService)
Of course, the
HeroListComponent
should do something with the injected HeroService
. Here's the revised component, making use of the injected service, side-by-side with the previous version for comparison.
Notice that the
HeroListComponent
doesn't know where the HeroService
comes from. You know that it comes from the parent HeroesComponent
. If you decided instead to provide the HeroService
in the AppModule
, the HeroListComponent
wouldn't change at all. The only thing that matters is that the HeroService
is provided in some parent injector.Singleton services
Services are singletons within the scope of an injector. There is at most one instance of a service in a given injector.
There is only one root injector, and the
UserService
is registered with that injector. Therefore, there can be just one UserService
instance in the entire app, and every class that injects UserService
get this service instance.
However, Angular DI is a hierarchical injection system, which means that nested injectors can create their own service instances. Angular creates nested injectors all the time.
Component child injectors
Component injectors are independent of each other and each of them creates its own instances of the component-provided services.
For example, when Angular creates a new instance of a component that has
@Component.providers
, it also creates a new child injector for that instance.
When Angular destroys one of these component instances, it also destroys the component's injector and that injector's service instances.
Because of injector inheritance, you can still inject application-wide services into these components. A component's injector is a child of its parent component's injector, and a descendent of its parent's parent's injector, and so on all the way back to the application's root injector. Angular can inject a service provided by any injector in that lineage.
For example, Angular could inject a
HeroListComponent
with both the HeroService
provided in HeroComponent
and the UserService
provided in AppModule
.Testing the component
Earlier you saw that designing a class for dependency injection makes the class easier to test. Listing dependencies as constructor parameters may be all you need to test application parts effectively.
For example, you can create a new
HeroListComponent
with a mock service that you can manipulate under test:const expectedHeroes = [{name: 'A'}, {name: 'B'}]
const mockService = <HeroService> {getHeroes: () => expectedHeroes }
it('should have heroes when HeroListComponent created', () => {
// Pass the mock to the constructor as the Angular injector would
const component = new HeroListComponent(mockService);
expect(component.heroes.length).toEqual(expectedHeroes.length);
});
Learn more in the Testing guide.
When the service needs a service
The
HeroService
is very simple. It doesn't have any dependencies of its own.
What if it had a dependency? What if it reported its activities through a logging service? You'd apply the same constructor injection pattern, adding a constructor that takes a
Logger
parameter.
Here is the revised
HeroService
that injects the Logger
, side-by-side with the previous service for comparison.
The constructor asks for an injected instance of a
Logger
and stores it in a private field called logger
. The getHeroes()
method logs a message when asked to fetch heroes.The dependent Logger service
The sample app's
Logger
service is quite simple:import { Injectable } from '@angular/core';
@Injectable()
export class Logger {
logs: string[] = []; // capture logs for testing
log(message: string) {
this.logs.push(message);
console.log(message);
}
}
If the app didn't provide this
Logger
, Angular would throw an exception when it looked for a Logger
to inject into the HeroService
.ERROR Error: No provider for Logger!
Because a singleton logger service is useful everywhere, it's provided in the root
AppModule
.providers: [
Logger,
UserService,
{ provide: APP_CONFIG, useValue: HERO_DI_CONFIG }
],
Dependency injection tokens
When you register a provider with an injector, you associate that provider with a dependency injection token. The injector maintains an internal token-provider map that it references when asked for a dependency. The token is the key to the map.
In all previous examples, the dependency value has been a class instance, and the class type served as its own lookup key. Here you get a
HeroService
directly from the injector by supplying the HeroService
type as the token:heroService: HeroService;
You have similar good fortune when you write a constructor that requires an injected class-based dependency. When you define a constructor parameter with the
HeroService
class type, Angular knows to inject the service associated with that HeroService
class token:constructor(heroService: HeroService)
This is especially convenient when you consider that most dependency values are provided by classes.
Non-class dependencies
What if the dependency value isn't a class? Sometimes the thing you want to inject is a string, function, or object.
Applications often define configuration objects with lots of small facts (like the title of the application or the address of a web API endpoint) but these configuration objects aren't always instances of a class. They can be object literals such as this one:
export const HERO_DI_CONFIG: AppConfig = {
apiEndpoint: 'api.heroes.com',
title: 'Dependency Injection'
};
What if you'd like to make this configuration object available for injection? You know you can register an object with a value provider.
But what should you use as the token? You don't have a class to serve as a token. There is no
AppConfig
class.TypeScript interfaces aren't valid tokens
The
HERO_DI_CONFIG
constant conforms to the AppConfig
interface. Unfortunately, you cannot use a TypeScript interface as a token:// FAIL! Can't use interface as provider token
[{ provide: AppConfig, useValue: HERO_DI_CONFIG })]
// FAIL! Can't inject using the interface as the parameter type
constructor(private config: AppConfig){ }
That seems strange if you're used to dependency injection in strongly typed languages, where an interface is the preferred dependency lookup key.
It's not Angular's doing. An interface is a TypeScript design-time artifact. JavaScript doesn't have interfaces. The TypeScript interface disappears from the generated JavaScript. There is no interface type information left for Angular to find at runtime.
InjectionToken
One solution to choosing a provider token for non-class dependencies is to define and use an InjectionToken. The definition of such a token looks like this:
import { InjectionToken } from '@angular/core';
export const TOKEN = new InjectionToken('desc');
You can directly configure a provider when creating an
InjectionToken
. The provider configuration determines which injector provides the token and how the value will be created. This is similar to using @Injectable
, except that you cannot define standard providers (such as useClass
or useFactory
) with InjectionToken
. Instead, you specify a factory function which returns the value to be provided directly.export const TOKEN =
new InjectionToken('desc', { providedIn: 'root', factory: () => new AppConfig(), })
Now you can inject the configuration object into any constructor that needs it, with the help of an
@Inject
decorator:constructor(@Inject(TOKEN));
If the factory function needs access to other DI tokens, it can use the inject function from
@angular/core
to request dependencies.const TOKEN =
new InjectionToken('tree-shakeable token',
{ providedIn: 'root', factory: () =>
new AppConfig(inject(Parameter1), inject(Paremeter2)), });
Optional dependencies
You can tell Angular that the dependency is optional by annotating the constructor argument with null:
constructor(@Inject(Token, null));
When using optional dependencies, your code must be prepared for a null value.
Summary
You learned the basics of Angular dependency injection in this page. You can register various kinds of providers, and you know how to ask for an injected object (such as a service) by adding a parameter to a constructor.
Angular dependency injection is more capable than this guide has described. You can learn more about its advanced features, beginning with its support for nested injectors, in Hierarchical Dependency Injection.
Appendix: Working with injectors directly
Developers rarely work directly with an injector, but here's an
InjectorComponent
that does.
- @Component({
- selector: 'app-injectors',
- template: `
-
Other Injections
-
{{car.drive()}}
-
{{hero.name}}
-
{{rodent}}
- `,
- providers: [Car, Engine, Tires, heroServiceProvider, Logger]
- })
- export class InjectorComponent implements OnInit {
- car: Car;
-
- heroService: HeroService;
- hero: Hero;
-
- constructor(private injector: Injector) { }
-
- ngOnInit() {
- this.car = this.injector.get(Car);
- this.heroService = this.injector.get(HeroService);
- this.hero = this.heroService.getHeroes()[0];
- }
-
- get rodent() {
- let rousDontExist = `R.O.U.S.'s? I don't think they exist!`;
- return this.injector.get(ROUS, rousDontExist);
- }
- }
An
Injector
is itself an injectable service.
In this example, Angular injects the component's own
Injector
into the component's constructor. The component then asks the injected injector for the services it wants in ngOnInit()
.
Note that the services themselves are not injected into the component. They are retrieved by calling
injector.get()
.
The
get()
method throws an error if it can't resolve the requested service. You can call get()
with a second parameter, which is the value to return if the service is not found. Angular can't find the service if it's not registered with this or any ancestor injector.
The technique is an example of the service locator pattern.
Avoid this technique unless you genuinely need it. It encourages a careless grab-bag approach such as you see here. It's difficult to explain, understand, and test. You can't know by inspecting the constructor what this class requires or what it will do. It could acquire services from any ancestor component, not just its own. You're forced to spelunk the implementation to discover what it does.
Framework developers may take this approach when they must acquire services generically and dynamically.
Appendix: one class per file
Having multiple classes in the same file is confusing and best avoided. Developers expect one class per file. Keep them happy.
If you combine the
HeroService
class with the HeroesComponent
in the same file, define the component last. If you define the component before the service, you'll get a runtime null reference error.
You actually can define the component first with the help of the
forwardRef()
method as explained in this blog post.
But it's best to avoid the problem altogether by defining components and services in separate files.
Comments
Post a Comment