From 4506230fbbae7e5c0e30b2b99096ed86751383d9 Mon Sep 17 00:00:00 2001 From: Vani Date: Thu, 29 Mar 2018 16:03:59 -0700 Subject: [PATCH] docs: update contents to recommend new way of defining providers (#23076) PR Close #23076 --- .../guide/dependency-injection-in-action.md | 83 +++++-------------- 1 file changed, 20 insertions(+), 63 deletions(-) diff --git a/aio/content/guide/dependency-injection-in-action.md b/aio/content/guide/dependency-injection-in-action.md index 46a6cd11d5..358feb1cdf 100644 --- a/aio/content/guide/dependency-injection-in-action.md +++ b/aio/content/guide/dependency-injection-in-action.md @@ -11,21 +11,18 @@ of the code in this cookbook. {@a app-wide-dependencies} ## Application-wide dependencies -Register providers for dependencies used throughout the application in the root application component, `AppComponent`. - -The following example shows importing and registering -the `LoggerService`, `UserContext`, and the `UserService` -in the `@Component` metadata `providers` array. - - - +Register providers for dependencies used throughout the application +in the `@Injectable()` decorator of the service itself. + +`providedIn` here tells Angular that the root injector is responsible for creating an instance of the `HeroService`. +Services that are provided this way are automatically made available to the entire +application and don't need to be listed in any module. -All of these services are implemented as classes. -Service classes can act as their own providers which is why listing them in the `providers` array +Service classes can act as their own providers which is why defining them in the `@Injectable` decorator is all the registration you need.
@@ -40,30 +37,21 @@ guide.
- Now that you've registered these services, Angular can inject them into the constructor of *any* component or service, *anywhere* in the application. - - - - - - - - - {@a external-module-configuration} ## External module configuration -Generally, register providers in the `NgModule` rather than in the root application component. +If a provider cannot be configured in the `@Injectable` decorator of the service, then register application-wide providers in the root `AppModule`, not in the `AppComponent`. Generally, register providers in the `NgModule` rather than in the root application component. -Do this when you expect the service to be injectable everywhere, -or you are configuring another application global service _before the application starts_. +Do this when users should explicitly opt-in to use a service, or the service should be +provided in a lazily-loaded context, +or when you are configuring another application global service _before the application starts_. -Here is an example of the second case, where the component router configuration includes a non-default +Here is an example of the case where the component router configuration includes a non-default [location strategy](guide/router#location-strategy) by listing its provider in the `providers` list of the `AppModule`. @@ -139,41 +127,7 @@ Notice the `@Injectable()`decorator on the `UserContextService` class. - -That decorator makes it possible for Angular to identify the types of its two dependencies, `LoggerService` and `UserService`. - -Technically, the `@Injectable()`decorator is only required for a service class that has _its own dependencies_. -The `LoggerService` doesn't depend on anything. The logger would work if you omitted `@Injectable()` -and the generated code would be slightly smaller. - -But the service would break the moment you gave it a dependency and you'd have to go back -and add `@Injectable()` to fix it. Add `@Injectable()` from the start for the sake -of consistency and to avoid future pain. - - -
- - - -Although this site recommends applying `@Injectable()` to all service classes, don't feel bound by it. -Some developers prefer to add it only where needed and that's a reasonable policy too. - - -
- - - -
- - - -The `AppComponent` class had two dependencies as well but no `@Injectable()`. -It didn't need `@Injectable()` because that component class has the `@Component` decorator. -In Angular with TypeScript, a *single* decorator—*any* decorator—is sufficient to identify dependency types. - - - -
+The `@Injectable` decorator indicates that the Angular DI system is used to create one or more instances of `UserContextService`. {@a service-scope} @@ -495,7 +449,7 @@ If the search is futile, the injector throws an error—unless the request w A new injector has no providers. Angular initializes the injectors it creates with some providers it cares about. You have to register your _own_ application providers manually, -usually in the `providers` array of the `Component` or `Directive` metadata: +usually in the `@Injectable` decorator of the service, `providers` array of the `NgModule` or `Directive` metadata: @@ -508,15 +462,18 @@ usually in the `providers` array of the `Component` or `Directive` metadata: ### Defining providers -The simple class provider is the most typical by far. -You mention the class in the `providers` array and you're done. +The simple way of defining providers in the `@Injectable` decorator of the class is recommended. + + + + +Another alternative is to mention the class in the providers array of the `@NgModule` and you're done. - It's that simple because the most common injected service is an instance of a class. But not every dependency can be satisfied by creating a new instance of a class. You need other ways to deliver dependency values and that means you need other ways to specify a provider.