Questa è la AWS CDK v2 Developer Guide. Il vecchio CDK v1 è entrato in manutenzione il 1° giugno 2022 e ha terminato il supporto il 1° giugno 2023.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Configurazione dei messaggi e delle interazioni di CDK Toolkit
<a name="toolkit-library-configure-messages"></a>

La AWS CDK Toolkit Library fornisce l'` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/IIoHost/) `interfaccia per personalizzare il modo in cui i messaggi e le interazioni vengono gestiti durante le operazioni CDK, consentendovi di controllare la visualizzazione dello stato di avanzamento della distribuzione, dei messaggi di errore e delle istruzioni utente per una migliore integrazione con l'esperienza utente dell'applicazione.

Prima di eseguire operazioni come l'implementazione o la sintesi, è necessario comprendere come CDK Toolkit comunica con gli utenti. L'`IIoHost`interfaccia funge da canale di comunicazione tra CDK Toolkit e l'applicazione, gestendo sia i messaggi in uscita che le risposte degli utenti in entrata.

Quando CDK Toolkit esegue le operazioni, comunica attraverso due meccanismi principali:
+  **Messaggi**: output informativi che informano l'utente sullo stato di avanzamento dell'operazione (come «Avvio della distribuzione» o «Creazione di risorse»).
+  **Richieste**: punti decisionali che richiedono l'immissione o la conferma (ad esempio «Vuoi implementare queste modifiche?») , offrendoti l'opportunità di fornire informazioni che prima non erano ritenute necessarie.

## Utilizzo dell'interfaccia `IIoHost`
<a name="toolkit-library-configure-messages-iiohost"></a>

L'`IIoHost`interfaccia è costituita da due metodi principali:

1.  `notify`: gestisce i messaggi informativi unidirezionali.

1.  `requestResponse`: gestisce le richieste interattive che richiedono una risposta.

```
import { IoMessage, IoRequest } from '@aws-cdk/toolkit-lib';

interface IIoHost {
  // Handle informational messages
  notify(message: IoMessage): Promise<void>;

  // Handle requests that need responses
  requestResponse(request: IoRequest): Promise<any>;
}
```

## Livelli di messaggi e tipi di richieste
<a name="toolkit-library-configure-messages-levels"></a>

Il CDK Toolkit genera diversi tipi di messaggi e richieste:

### Livelli di messaggio
<a name="_message_levels"></a>
+  **Debug**: messaggi dettagliati per la risoluzione dei problemi.
+  **Errore**: messaggi di errore che possono influire sul funzionamento.
+  **Informazioni**: messaggi informativi generali.
+  **Risultato**: messaggio principale di un'operazione.
+  **Trace**: informazioni molto dettagliate sul flusso di esecuzione.
+  **Avviso**: messaggi di avviso che non impediscono il funzionamento.

Per un elenco completo, consultate [IoMessages Registry](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) nel riferimento all'*API AWS CDK Toolkit Library*.

### Tipi di richieste
<a name="_request_types"></a>

CDK Toolkit invia richieste quando necessita di input o conferma da parte dell'utente. Si tratta di messaggi speciali che consentono una risposta. Se non viene fornita alcuna risposta, il Toolkit utilizzerà una risposta predefinita quando disponibile.

## implementazione di base `IIoHost`
<a name="toolkit-library-configure-messages-basic"></a>

Ecco un semplice esempio di implementazione di un host io personalizzato:

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Create a toolkit with custom message handling
const toolkit = new Toolkit({
  ioHost: {
    // Implementing the IIoHost interface
    // Handle informational messages
    notify: async function (msg) {
      // Example: Handle different message levels appropriately
      switch (msg.level) {
        case 'error':
          console.error(`[${msg.time}] ERROR: ${msg.message}`);
          break;
        case 'warning':
          console.warn(`[${msg.time}] WARNING: ${msg.message}`);
          break;
        case 'info':
          console.info(`[${msg.time}] INFO: ${msg.message}`);
          break;
        case 'debug':
          console.debug(`[${msg.time}] DEBUG: ${msg.message}`);
          break;
        case 'trace':
          console.debug(`[${msg.time}] TRACE: ${msg.message}`);
          break;
        default:
          console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
      }
    },

    // Handle requests that need responses
    requestResponse: async function (msg) {
      // Example: Log the request and use default response
      console.log(`Request: ${msg.message}, using default: ${msg.defaultResponse}`);
      return msg.defaultResponse;

      // Or implement custom logic to provide responses
      // if (msg.type === 'deploy') {
      //   return promptUserForDeployment(msg);
      // }
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```

Il CDK Toolkit attende il completamento di ogni chiamata e consente di eseguire operazioni asincrone come richieste HTTP o istruzioni utente durante la gestione dei messaggi.

## Comportamento predefinito `IIoHost`
<a name="toolkit-library-configure-messages-iiohost-default"></a>

Se non fornite un host io personalizzato, la CDK Toolkit Library utilizza un'implementazione non interattiva predefinita:
+ Output da console per i messaggi (utilizzando colori appropriati per diversi tipi di messaggi).
+ Completamente non interattivo senza richieste di input da parte dell'utente.
+ Utilizza automaticamente le risposte predefinite laddove possibile (equivalente a rispondere «sì» alle richieste).
+ Fallisce quando è richiesto un input ma non è disponibile una risposta predefinita.

Questo comportamento predefinito è adatto per le operazioni non presidiate, ma non per le applicazioni interattive a riga di comando. Per le applicazioni da riga di comando che richiedono l'interazione dell'utente, è necessario implementare un host io personalizzato. Le implementazioni personalizzate sono utili anche per l'integrazione con sistemi di registrazione o altri ambienti specializzati UIs.

## Implementazione avanzata dell'host io
<a name="toolkit-library-configure-messages-advanced"></a>

Per scenari più complessi, consigliamo di estendere la `NonInteractiveIoHost` classe come punto di partenza. Questo approccio consente di sfruttare l'implementazione non interattiva esistente personalizzando solo i comportamenti specifici che è necessario modificare.

Ecco un esempio di un host io personalizzato che estende l'implementazione di base:

```
import { NonInteractiveIoHost } from '@aws-cdk/toolkit-lib';

class MyCustomIoHost extends NonInteractiveIoHost {
  // Override only the methods you need to customize

  // Example: Custom implementation for notify
  public async notify(msg: IoMessage<unknown>): Promise<void> {
    // Add custom notification handling logic
    if (msg.level === 'error') {
      console.error(`ERROR: ${msg.message}`);
      // Optionally log to a service or notify a monitoring system
      await this.logToMonitoringService(msg);
    } else {
      await super.notify(msg);
    }
  }

  // Example: Custom implementation for requestResponse
  public async requestResponse<T, U>(request: IoRequest<T, U>): Promise<U> {
    // Implement custom request handling
    console.log(`Received request: ${request.message}`);
    return request.defaultResponse;
  }

  private async logToMonitoringService(msg: IoMessage<unknown>): Promise<void> {
    // Implementation for monitoring service integration
    console.log(`Logging to monitoring service: ${msg.level} - ${msg.message}`);
  }
}
```

Questo approccio è più gestibile rispetto all'implementazione dell'intera `IIoHost` interfaccia da zero, poiché è sufficiente sovrascrivere i metodi specifici che richiedono un comportamento personalizzato.

## Integrazione con ambienti diversi
<a name="toolkit-library-configure-messages-integration"></a>

### Integrazione di applicazioni Web
<a name="_web_application_integration"></a>

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Example for integrating with a web application
const toolkit = new Toolkit({
  ioHost: {
    notify: async function (msg) {
      // Send message to frontend via WebSocket
      webSocketServer.send(JSON.stringify({
        type: 'cdk-notification',
        messageLevel: msg.level,
        message: msg.message,
        time: msg.time
      }));
    },

    requestResponse: async function (msg) {
      // Create a promise that will be resolved when the user responds
      return new Promise((resolve) => {
        const requestId = generateUniqueId();

        // Store the resolver function
        pendingRequests[requestId] = resolve;

        // Send request to frontend
        webSocketServer.send(JSON.stringify({
          type: 'cdk-request',
          requestId: requestId,
          requestType: msg.type,
          message: msg.message,
          defaultResponse: msg.defaultResponse
        }));

        // Frontend would call an API endpoint with the response,
        // which would then call pendingRequests[requestId](response)
      });
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```

### Integrazione dell'ambiente CI/CD
<a name="_cicd_environment_integration"></a>

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Example for CI/CD environments (non-interactive)
const toolkit = new Toolkit({
  ioHost: {
    notify: async function (msg) {
      // Log all messages with appropriate level
      switch (msg.level) {
        case 'error':
          console.error(msg.message);
          break;
        case 'warning':
          console.warn(msg.message);
          break;
        default:
          console.log(msg.message);
      }
    },

    requestResponse: async function (msg) {
      // In CI/CD, always use default responses or predefined answers
      console.log(`Auto-responding to request: ${msg.message} with ${msg.defaultResponse}`);
      return msg.defaultResponse;
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```

## Le migliori pratiche per l'implementazione di io host
<a name="toolkit-library-configure-messages-best-practices"></a>

Quando implementi un host io personalizzato, prendi in considerazione queste best practice:
+  **Gestione degli errori**: implementate una solida gestione degli errori nei metodi degli host io per evitare che gli errori influiscano sulle operazioni CDK.
+  **Timeout**: prendete in considerazione l'implementazione di timeout per le interazioni con gli utenti per evitare attese indefinite.
+  **Registrazione**: archivia i messaggi importanti nei registri per la risoluzione dei problemi, specialmente in ambienti non interattivi.
+  **Risposte predefinite: fornisce risposte** predefinite ragionevoli per ambienti automatizzati in cui l'interazione dell'utente non è possibile.
+  **Indicazione dello stato di avanzamento**: per le operazioni di lunga durata, fornisci indicatori di avanzamento chiari per migliorare l'esperienza dell'utente.

L'esempio seguente dimostra queste best practice implementando un host io personalizzato con gestione degli errori, timeout per le interazioni con gli utenti e registrazione corretta. Questa implementazione è adatta per applicazioni interattive in cui è necessario bilanciare la reattività dell'utente con un funzionamento affidabile:

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Example with error handling and timeouts
const toolkit = new Toolkit({
  ioHost: {
    notify: async function (msg) {
      try {
        console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
        // Additional logging or UI updates
      } catch (error) {
        // Ensure errors in notification handling don't break the CDK operation
        console.error("Error handling notification:", error);
      }
    },

    requestResponse: async function (msg) {
      try {
        // Implement timeout for user response
        const response = await Promise.race([
          getUserResponse(msg),
          new Promise(resolve => setTimeout(() => resolve(msg.defaultResponse), 60000))
        ]);
        return response;
      } catch (error) {
        console.error("Error handling request:", error);
        return msg.defaultResponse;
      }
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```

## Risoluzione dei problemi
<a name="toolkit-library-configure-messages-troubleshooting"></a>

Considerazioni sull'implementazione di un host io personalizzato:
+  **Rifiuti di promesse non gestiti**: assicurati che tutte le operazioni asincrone siano gestite correttamente con i blocchi try/catch.
+  **Attesa infinita**: implementa i timeout per tutte le interazioni degli utenti per evitare che l'applicazione si blocchi.
+  **Livelli di messaggio mancanti**: preparatevi a gestire nuovi livelli di messaggio che potrebbero essere aggiunti nelle future versioni di CDK.
+  **Risposte incoerenti**: assicurati che l'implementazione di RequestResponse restituisca valori nel formato previsto.

L'esempio seguente dimostra un approccio robusto alla gestione dei livelli di messaggio, inclusa la gestione corretta di tipi di messaggi sconosciuti che potrebbero essere introdotti nelle future versioni di CDK. Questa implementazione garantisce che il tuo host io rimanga compatibile con gli aggiornamenti CDK mantenendo una registrazione corretta:

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Example of handling unknown message levels
const toolkit = new Toolkit({
  ioHost: {
    notify: async function (msg) {
      // Handle known levels
      const knownLevels = ['info', 'warning', 'error', 'debug', 'trace', 'status'];

      if (knownLevels.includes(msg.level)) {
        // Handle known level
        handleKnownMessageLevel(msg);
      } else {
        // Handle unknown level as info
        console.log(`Unknown message level "${msg.level}": ${msg.message}`);
      }
    },

    requestResponse: async function (msg) {
      // Default implementation
      return msg.defaultResponse;
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```