class Annotations

Language	Type name
.NET	Amazon.CDK.Annotations
Go	github.com/aws/aws-cdk-go/awscdk/v2#Annotations
Java	software.amazon.awscdk.Annotations
Python	aws_cdk.Annotations
TypeScript (source)	aws-cdk-lib » Annotations

Includes API for attaching annotations such as warning messages to constructs.

Example

import * as cdk from 'aws-cdk-lib';
import { Construct, IConstruct } from 'constructs';

class MyAspect implements cdk.IAspect {
  public visit(node: IConstruct): void {
    if (node instanceof cdk.CfnResource && node.cfnResourceType === 'Foo::Bar') {
      this.error(node, 'we do not want a Foo::Bar resource');
    }
  }

  protected error(node: IConstruct, message: string): void {
    cdk.Annotations.of(node).addError(message);
  }
}

class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const stack = new cdk.Stack();
    new cdk.CfnResource(stack, 'Foo', {
      type: 'Foo::Bar',
      properties: {
        Fred: 'Thud',
      },
    });
    cdk.Aspects.of(stack).add(new MyAspect());
  }
}

Methods

Name	Description
acknowledgeInfo(id, message?)	Acknowledge a info. When a info is acknowledged for a scope all infos that match the id will be ignored.
acknowledgeWarning(id, message?)	Acknowledge a warning. When a warning is acknowledged for a scope all warnings that match the id will be ignored.
addDeprecation(api, message)	Adds a deprecation warning for a specific API.
addError(message)	Adds an { "error": <message> } metadata entry to this construct.
addInfo(message)	Adds an info metadata entry to this construct.
addInfoV2(id, message)	Adds an acknowledgeable info metadata entry to this construct.
addWarning(message)	Adds a warning metadata entry to this construct. Prefer using addWarningV2.
addWarningV2(id, message)	Adds an acknowledgeable warning metadata entry to this construct.
static of(scope)	Returns the annotations API for a construct scope.

---

acknowledgeInfo(id, message?)

public acknowledgeInfo(id: string, message?: string): void

Parameters

• id string — - the id of the info message to acknowledge.
• message string — optional message to explain the reason for acknowledgement.

Acknowledge a info. When a info is acknowledged for a scope all infos that match the id will be ignored.

The acknowledgement will apply to all child scopes Example

declare const myConstruct: Construct;
Annotations.of(myConstruct).acknowledgeInfo('SomeInfoId', 'This info can be ignored because...');

---

acknowledgeWarning(id, message?)

public acknowledgeWarning(id: string, message?: string): void

Parameters

• id string — - the id of the warning message to acknowledge.
• message string — optional message to explain the reason for acknowledgement.

Acknowledge a warning. When a warning is acknowledged for a scope all warnings that match the id will be ignored.

The acknowledgement will apply to all child scopes Example

declare const myConstruct: Construct;
Annotations.of(myConstruct).acknowledgeWarning('SomeWarningId', 'This warning can be ignored because...');

---

addDeprecation(api, message)

public addDeprecation(api: string, message: string): void

Parameters

• api string — The API being deprecated in the format module.Class.property (e.g. @aws-cdk/core.Construct.node).
• message string — The deprecation message to display, with information about alternatives.

Adds a deprecation warning for a specific API.

Deprecations will be added only once per construct as a warning and will be deduplicated based on the api.

If the environment variable CDK_BLOCK_DEPRECATIONS is set, this method will throw an error instead with the deprecation message.

---

addError(message)

public addError(message: string): void

Parameters

• message string — The error message.

Adds an { "error": <message> } metadata entry to this construct.

The toolkit will fail deployment of any stack that has errors reported against it.

---

addInfo(message)

public addInfo(message: string): void

Parameters

• message string — The info message.

Adds an info metadata entry to this construct.

The CLI will display the info message when apps are synthesized.

---

addInfoV2(id, message)

public addInfoV2(id: string, message: string): void

Parameters

• id string — the unique identifier for the info.
• message string — The info message.

Adds an acknowledgeable info metadata entry to this construct.

The CLI will display the info when an app is synthesized.

If the info is acknowledged using acknowledgeInfo(), it will not be shown by the CLI. Example

declare const myConstruct: Construct;
Annotations.of(myConstruct).addInfoV2('my-library:Construct.someInfo', 'Some message explaining the info');

---

addWarning(message)

public addWarning(message: string): void

Parameters

• message string — The warning message.

Adds a warning metadata entry to this construct. Prefer using addWarningV2.

The CLI will display the warning when an app is synthesized, or fail if run in --strict mode.

Warnings added by this call cannot be acknowledged. This will block users from running in --strict mode until the deal with the warning, which makes it effectively not very different from addError. Prefer using addWarningV2 instead.

---

addWarningV2(id, message)

public addWarningV2(id: string, message: string): void

Parameters

• id string — the unique identifier for the warning.
• message string — The warning message.

Adds an acknowledgeable warning metadata entry to this construct.

The CLI will display the warning when an app is synthesized, or fail if run in --strict mode.

If the warning is acknowledged using acknowledgeWarning(), it will not be shown by the CLI, and will not cause --strict mode to fail synthesis. Example

declare const myConstruct: Construct;
Annotations.of(myConstruct).addWarningV2('my-library:Construct.someWarning', 'Some message explaining the warning');

---

static of(scope)

public static of(scope: IConstruct): Annotations

Parameters

• scope IConstruct — The scope.

Returns

• Annotations

Returns the annotations API for a construct scope.