docs(router): Deprecate public members of Router that are meant to be configured elsewhere (#48006)

atscott · dylhunn · commit 0a8b8a66cdfb · 2022-11-17T09:26:20.000-08:00
None of the public properties of the `Router` are meant to be writeable. They should all be configured using other methods, all of which have been documented. DEPRECATED: router writable properties The following strategies are meant to be configured by registering the application strategy in DI via the `providers` in the root `NgModule` or `bootstrapApplication`: * `routeReuseStrategy` * `titleStrategy` * `urlHandlingStrategy` The following options are meant to be configured using the options available in `RouterModule.forRoot` or `provideRouter`. * `onSameUrlNavigation` * `paramsInheritanceStrategy` * `urlUpdateStrategy` * `canceledNavigationResolution` The following options are available in `RouterModule.forRoot` but not available in `provideRouter`: * `malformedUriErrorHandler` - This was found to not be used anywhere internally. * `errorHandler` - Developers can instead subscribe to `Router.events` and filter for `NavigationError`. PR Close #48006
diff --git a/aio/content/guide/deprecations.md b/aio/content/guide/deprecations.md
@@ -115,6 +115,7 @@ v15 - v18
 | `@angular/common`                   | [`DatePipe` - `DATE_PIPE_DEFAULT_TIMEZONE`](api/common/DATE_PIPE_DEFAULT_TIMEZONE)                         | v15           | v17         |
 | `@angular/core`                     | NgModule and `'any'` options for [`providedIn`](#core)                                                     | v15           | v17         |
 | `@angular/router`                   | [`RouterLinkWithHref` directive](#router)                                                                  | v15           | v17         |
+| `@angular/router`                   | [Router writeable properties](#router-writable-properties)                                                 | v15.1         | v17         |
 
 ### Deprecated features with no planned removal version
 
@@ -375,6 +376,33 @@ The injector no longer requires the Reflect polyfill, reducing application size
 
 <code-example path="deprecation-guide/src/app/app.component.ts" language="typescript" region="static-injector-example"></code-example>
 
+<a id="router-writable-properties"></a>
+
+None of the public properties of the `Router` are meant to be writeable.
+They should all be configured using other methods, all of which have been
+documented.
+
+The following strategies are meant to be configured by registering the
+application strategy in DI via the `providers` in the root `NgModule` or
+`bootstrapApplication`:
+* `routeReuseStrategy`
+* `titleStrategy`
+* `urlHandlingStrategy`
+
+The following options are meant to be configured using the options
+available in `RouterModule.forRoot` or `provideRouter` and `withRouterConfig`.
+* `onSameUrlNavigation`
+* `paramsInheritanceStrategy`
+* `urlUpdateStrategy`
+* `canceledNavigationResolution`
+
+The following options are available in `RouterModule.forRoot` but not
+available in `provideRouter`:
+* `malformedUriErrorHandler` - This was not found to be used by anyone.
+  There are currently no plans to make this available in `provideRouter`.
+* `errorHandler` - Developers should instead subscribe to `Router.events`
+  and filter for `NavigationError`.
+
 <a id="relativeLinkResolution"></a>
 
 The `relativeLinkResolution` option is deprecated and being removed.
diff --git a/goldens/public-api/router/index.md b/goldens/public-api/router/index.md
@@ -630,35 +630,44 @@ export class RouteConfigLoadStart {
 // @public
 export class Router {
     constructor(rootComponentType: Type<any> | null, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location_2, injector: Injector, compiler: Compiler, config: Routes);
+    // @deprecated
     canceledNavigationResolution: 'replace' | 'computed';
     // (undocumented)
     config: Routes;
     createUrlTree(commands: any[], navigationExtras?: UrlCreationOptions): UrlTree;
     dispose(): void;
+    // @deprecated
     errorHandler: ErrorHandler;
     readonly events: Observable<Event_2>;
     getCurrentNavigation(): Navigation | null;
     initialNavigation(): void;
     // @deprecated
     isActive(url: string | UrlTree, exact: boolean): boolean;
     isActive(url: string | UrlTree, matchOptions: IsActiveMatchOptions): boolean;
+    // @deprecated
     malformedUriErrorHandler: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree;
     navigate(commands: any[], extras?: NavigationExtras): Promise<boolean>;
     navigateByUrl(url: string | UrlTree, extras?: NavigationBehaviorOptions): Promise<boolean>;
     navigated: boolean;
     // (undocumented)
     ngOnDestroy(): void;
+    // @deprecated
     onSameUrlNavigation: 'reload' | 'ignore';
+    // @deprecated
     paramsInheritanceStrategy: 'emptyOnly' | 'always';
     parseUrl(url: string): UrlTree;
     resetConfig(config: Routes): void;
+    // @deprecated
     routeReuseStrategy: RouteReuseStrategy;
     readonly routerState: RouterState;
     serializeUrl(url: UrlTree): string;
     setUpLocationChangeListener(): void;
+    // @deprecated
     titleStrategy?: TitleStrategy;
     get url(): string;
+    // @deprecated
     urlHandlingStrategy: UrlHandlingStrategy;
+    // @deprecated
     urlUpdateStrategy: 'deferred' | 'eager';
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<Router, never>;
diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts
@@ -429,6 +429,8 @@ export class Router {
 
   /**
    * A handler for navigation errors in this NgModule.
+   *
+   * @deprecated Subscribe to the `Router` events and watch for `NavigationError` instead.
    */
   errorHandler: ErrorHandler = defaultErrorHandler;
 
@@ -437,6 +439,10 @@ export class Router {
    * when `url` contains an invalid character.
    * The most common case is a `%` sign
    * that's not encoded and is not part of a percent encoded sequence.
+   *
+   * @deprecated Configure this through `RouterModule.forRoot` instead:
+   *   `RouterModule.forRoot(routes, {malformedUriErrorHandler: myHandler})`
+   * @see `RouterModule`
    */
   malformedUriErrorHandler:
       (error: URIError, urlSerializer: UrlSerializer,
@@ -460,16 +466,25 @@ export class Router {
   /**
    * A strategy for extracting and merging URLs.
    * Used for AngularJS to Angular migrations.
+   *
+   * @deprecated Configure using `providers` instead:
+   *   `{provide: UrlHandlingStrategy, useClass: MyStrategy}`.
    */
   urlHandlingStrategy = inject(UrlHandlingStrategy);
 
   /**
    * A strategy for re-using routes.
+   *
+   * @deprecated Configure using `providers` instead:
+   *   `{provide: RouteReuseStrategy, useClass: MyStrategy}`.
    */
   routeReuseStrategy = inject(RouteReuseStrategy);
 
   /**
    * A strategy for setting the title based on the `routerState`.
+   *
+   * @deprecated Configure using `providers` instead:
+   *   `{provide: TitleStrategy, useClass: MyStrategy}`.
    */
   titleStrategy?: TitleStrategy = inject(TitleStrategy);
 
@@ -485,6 +500,11 @@ export class Router {
    * component first. This behavior is configured by the `RouteReuseStrategy`. In order to reload
    * routed components on same url navigation, you need to set `onSameUrlNavigation` to `'reload'`
    * _and_ provide a `RouteReuseStrategy` which returns `false` for `shouldReuseRoute`.
+   *
+   * @deprecated Configure this through `provideRouter` or `RouterModule.forRoot` instead.
+   * @see `withRouterConfig`
+   * @see `provideRouter`
+   * @see `RouterModule`
    */
   onSameUrlNavigation: 'reload'|'ignore' = 'ignore';
 
@@ -496,6 +516,11 @@ export class Router {
    * for path-less or component-less routes.
    * - `'always'` : Inherit parent parameters, data, and resolved data
    * for all child routes.
+   *
+   * @deprecated Configure this through `provideRouter` or `RouterModule.forRoot` instead.
+   * @see `withRouterConfig`
+   * @see `provideRouter`
+   * @see `RouterModule`
    */
   paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly';
 
@@ -505,6 +530,11 @@ export class Router {
    * Set to `'eager'` to update the browser URL at the beginning of navigation.
    * You can choose to update early so that, if navigation fails,
    * you can show an error message with the URL that failed.
+   *
+   * @deprecated Configure this through `provideRouter` or `RouterModule.forRoot` instead.
+   * @see `withRouterConfig`
+   * @see `provideRouter`
+   * @see `RouterModule`
    */
   urlUpdateStrategy: 'deferred'|'eager' = 'deferred';
 
@@ -529,6 +559,10 @@ export class Router {
    *
    * The default value is `replace`.
    *
+   * @deprecated Configure this through `provideRouter` or `RouterModule.forRoot` instead.
+   * @see `withRouterConfig`
+   * @see `provideRouter`
+   * @see `RouterModule`
    */
   canceledNavigationResolution: 'replace'|'computed' = 'replace';
 
