CREATE QUEUE (Transact-SQL)

Crea una nuova coda in un database. Le code vengono utilizzate per archiviare messaggi. Quando viene recapitato un messaggio per un servizio, Service Broker inserisce il messaggio nella coda associata al servizio.

Convenzioni della sintassi Transact-SQL

Sintassi

CREATE QUEUE <object>
   [ WITH
     [ STATUS = { ON | OFF }  [ , ] ]
     [ RETENTION = { ON | OFF } [ , ] ] 
     [ ACTIVATION (
         [ STATUS = { ON | OFF } , ] 
           PROCEDURE_NAME = <procedure> ,
           MAX_QUEUE_READERS = max_readers , 
           EXECUTE AS { SELF | 'user_name' | OWNER } 
            ) [ , ] ]
     [ POISON_MESSAGE_HANDLING (
       [ STATUS = { ON | OFF } )
    ]
     [ ON { filegroup | [ DEFAULT ] } ]
[ ; ]

<object> ::=
{
    [ database_name. [ schema_name ] . | schema_name. ]
        queue_name
} 

<procedure> ::=
{
    [ database_name. [ schema_name ] . | schema_name. ]
        stored_procedure_name
} 

Argomenti

• database_name(oggetto)
  Nome del database in cui creare la nuova coda. database_name deve specificare il nome di un database esistente. Se non si specifica database_name, la coda viene creata nel database corrente.

• schema_name (oggetto)
  Nome dello schema cui appartiene la nuova coda. Per impostazione predefinita, viene utilizzato lo schema predefinito dell'utente che esegue l'istruzione. Se l'istruzione CREATE QUEUE viene eseguita da un membro del ruolo predefinito del server sysadmin o da un membro del ruolo predefinito del database db_dbowner o db_ddladmin nel database specificato da database_name, schema_name può specificare uno schema diverso da quello associato all'account di accesso della connessione corrente. In caso contrario, schema_name deve corrispondere allo schema predefinito per l'utente che esegue l'istruzione.

• queue_name
  Nome della coda da creare. Il nome deve essere conforme alle linee guida per gli identificatori di SQL Server.

• STATUS (coda)
  Specifica se la coda è disponibile (ON) o non disponibile (OFF). Quando la coda non è disponibile, non è possibile aggiungere o rimuovere messaggi nella coda. È possibile creare la coda con stato non disponibile per impedire che i messaggi raggiungano la coda fino a quando non viene resa disponibile con un'istruzione ALTER QUEUE. Se questa clausola viene omessa, il valore predefinito è ON e la coda è disponibile.

• RETENTION
  Specifica l'impostazione di memorizzazione per la coda. Se RETENTION = ON, tutti i messaggi inviati o ricevuti per conversazioni che utilizzano la coda vengono mantenuti nella coda fino al termine delle conversazioni. Questo consente di mantenere i messaggi a scopo di controllo oppure di eseguire transazioni di compensazione se si verificano errori. Se questa clausola viene omessa, il valore predefinito dell'impostazione di memorizzazione è OFF.

  Nota

  L'impostazione di RETENTION = ON può ridurre le prestazioni. È quindi consigliabile utilizzare questa impostazione solo se richiesto per l'applicazione. Per ulteriori informazioni, vedere Memorizzazione dei messaggi.

• ACTIVATION
  Specifica le informazioni sulla stored procedure da avviare per l'elaborazione dei messaggi nella coda.

• STATUS (attivazione)
  Specifica se Service Broker avvia la stored procedure. Se STATUS = ON, la coda avvia la stored procedure specificata con PROCEDURE_NAME quando il numero di procedure in esecuzione è minore di MAX_QUEUE_READERS e quando i messaggi arrivano nella coda più velocemente di quanto non vengano ricevuti dalle stored procedure. Se STATUS = OFF, la coda non avvia la stored procedure. Se questa clausola viene omessa, il valore predefinito è ON.

• PROCEDURE_NAME = <procedure>
  Specifica il nome della stored procedure da avviare per l'elaborazione dei messaggi nella coda. Il valore deve essere un identificatore di SQL Server. Per ulteriori informazioni, vedere Informazioni sull'esecuzione dell'attivazione.

• database_name(procedura)
  Nome del database contenente la stored procedure.

• schema_name(procedura)
  Nome dello schema contenente la stored procedure.

• procedure_name
  Nome della stored procedure.

• MAX_QUEUE_READERS = max_readers
  Specifica il numero massimo di istanze della stored procedure di attivazione avviate simultaneamente dalla coda. Il valore di max_readers deve essere un numero compreso tra 0 e 32767.

• EXECUTE AS
  Specifica l'account utente di database di SQL Server utilizzato per l'esecuzione della stored procedure di attivazione. SQL Server deve essere in grado di controllare le autorizzazioni per tale utente nel momento in cui la coda avvia la stored procedure. Nel caso di un utente di dominio, è necessario che il server sia connesso al dominio quando viene avviata la procedura. In caso contrario, l'attivazione ha esito negativo. Per un utente di SQL Server, il server è sempre in grado di eseguire il controllo delle autorizzazioni.

• SELF
  Specifica che la stored procedure viene eseguita con l'account dell'utente corrente, ovvero l'entità di database che esegue l'istruzione CREATE QUEUE.

• 'user_name'
  Nome dell'utente utilizzato per l'esecuzione della stored procedure. Il parametro user_name deve essere un utente di SQL Server valido specificato come identificatore di SQL Server. L'utente corrente deve disporre dell'autorizzazione IMPERSONATE per l'account user_name specificato.

• OWNER
  Specifica che la stored procedure viene eseguita con l'account del proprietario della coda.

• POISON_MESSAGE_HANDLING
  Specifica se la gestione del messaggio non elaborabile è abilitata per la coda. Il valore predefinito è ON.

  Una coda con la gestione di messaggi non elaborabili impostata su OFF non verrà disabilitata dopo cinque rollback di transazioni consecutivi. In questo modo è possibile che un sistema di gestione di messaggi non elaborabili venga definito dall'applicazione.

• ON filegroup | [ DEFAULT ]
  Specifica il filegroup di SQL Server in cui creare la coda. È possibile utilizzare il parametro filegroup per specificare un filegroup oppure utilizzare l'identificatore DEFAULT per utilizzare il filegroup predefinito del database di Service Broker. Nel contesto di questa clausola DEFAULT non è una parola chiave ed è pertanto necessario delimitarlo come identificatore. Se non si specifica un filegroup, per la coda viene utilizzato il filegroup predefinito del database.

Osservazioni

Una coda può essere la destinazione di un'istruzione SELECT. È tuttavia possibile modificare il contenuto di una coda solo tramite istruzioni che operano in conversazioni di Service Broker, quali SEND, RECEIVE e END CONVERSATION. Non è possibile specificare una coda come destinazione di un'istruzione INSERT, UPDATE, DELETE o TRUNCATE.

Una coda non può essere un oggetto temporaneo. Pertanto, i nomi di coda che iniziano con # non sono validi.

La creazione di una coda con stato inattivo consente di predisporre l'infrastruttura necessaria per un servizio prima di consentire la ricezione dei messaggi nella coda.

Service Broker non arresta le stored procedure di attivazione se non sono presenti messaggi nella coda. È consigliabile prevedere l'interruzione di una stored procedure di attivazione se nella coda non sono disponibili messaggi per un breve periodo di tempo.

Le autorizzazioni per la stored procedure di attivazione vengono controllate quando Service Broker avvia la stored procedure e non al momento della creazione della coda. L'istruzione CREATE QUEUE non verifica che l'utente specificato nella clausola EXECUTE AS disponga delle autorizzazioni per l'esecuzione della stored procedure specificata nella clausola PROCEDURE NAME.

Quando una coda non è disponibile, Service Broker mantiene i messaggi per i servizi che utilizzano tale coda nella coda di trasmissione per il database. La vista del catalogo sys.transmission_queue consente di visualizzare il contenuto della coda di trasmissione.

Una coda è un oggetto di proprietà dello schema. Le code sono incluse nella vista del catalogo sys.objects.

Nella tabella seguente vengono elencate le colonne di una coda.

Nome colonna	Tipo di dati	Descrizione
status	tinyint	Stato del messaggio. L'istruzione RECEIVE restituisce tutti i messaggi con stato 1. Se la memorizzazione dei messaggi è attiva, lo stato viene quindi impostato su 0. Se la memorizzazione dei messaggi è disattivata, il messaggio viene eliminato dalla coda. I messaggi nella coda possono contenere uno dei valori seguenti: 0 = Messaggio ricevuto memorizzato 1 = Pronto per la ricezione 2 = Non ancora completo 3 = Messaggio inviato memorizzato
priority	tinyint	Livello di priorità assegnato al messaggio.
queuing_order	bigint	Numero progressivo del messaggio nella coda.
conversation_group_id	uniqueidentifier	Identificatore del gruppo di conversazioni a cui appartiene il messaggio.
conversation_handle	uniqueidentifier	Handle della conversazione di cui fa parte il messaggio.
message_sequence_number	bigint	Numero di sequenza del messaggio nella conversazione.
service_name	nvarchar(512)	Nome del servizio a cui è destinata la conversazione.
service_id	int	Identificatore di oggetto di SQL Server del servizio a cui è destinata la conversazione.
service_contract_name	nvarchar(256)	Nome del contratto rispettato dalla conversazione.
service_contract_id	int	Identificatore di oggetto di SQL Server del contratto rispettato dalla conversazione.
message_type_name	nvarchar(256)	Nome del tipo di messaggio che descrive il messaggio.
message_type_id	int	Identificatore di oggetto di SQL Server del tipo di messaggio che descrive il messaggio.
validation	nchar(2)	Convalida utilizzata per il messaggio. E=Vuoto N=Nessuno X=XML
message_body	varbinary(MAX)	Contenuto del messaggio.
message_id	uniqueidentifier	Identificatore univoco del messaggio.

Autorizzazioni

L'autorizzazione per la creazione di una coda viene assegnata ai membri del ruolo predefinito del database db_ddladmin o db_owner e ai membri del ruolo predefinito del server sysadmin.

L'autorizzazione REFERENCES per una coda viene assegnata per impostazione predefinita al proprietario della coda, ai membri del ruolo predefinito del database db_ddladmin o db_owner e ai membri del ruolo predefinito del server sysadmin.

L'autorizzazione RECEIVE per una coda viene assegnata per impostazione predefinita al proprietario della coda, ai membri del ruolo predefinito del database db_owner e ai membri del ruolo predefinito del server sysadmin.

Esempi

A. Creazione di una coda senza parametri

Nell'esempio seguente viene creata una coda disponibile per la ricezione di messaggi. Per la coda non viene specificata alcuna stored procedure di attivazione.

CREATE QUEUE ExpenseQueue ;

B. Creazione di una coda non disponibile

Nell'esempio seguente viene creata una coda non disponibile per la ricezione di messaggi. Per la coda non viene specificata alcuna stored procedure di attivazione.

CREATE QUEUE ExpenseQueue WITH STATUS=OFF ;

C. Creazione di una coda e impostazione delle informazioni interne per l'attivazione

Nell'esempio seguente viene creata una coda disponibile per la ricezione di messaggi. La coda avvia la stored procedure expense_procedure quando un messaggio raggiunge la coda. La stored procedure viene eseguita con l'account ExpenseUser. La coda avvia al massimo 5 istanze della stored procedure.

CREATE QUEUE ExpenseQueue
    WITH STATUS=ON,
    ACTIVATION (
        PROCEDURE_NAME = expense_procedure,
        MAX_QUEUE_READERS = 5,
        EXECUTE AS 'ExpenseUser' ) ;

D. Creazione di una coda in un filegroup specifico

Nell'esempio seguente viene creata una coda nel filegroup ExpenseWorkFileGroup.

CREATE QUEUE ExpenseQueue
    ON ExpenseWorkFileGroup ;

E. Creazione di una coda con più parametri

Nell'esempio seguente viene creata una coda nel filegroup DEFAULT. La coda non è disponibile. I messaggi vengono memorizzati nella coda fino al termine della conversazione cui appartengono. Quando viene resa disponibile tramite ALTER QUEUE, la coda avvia la stored procedure 2008R2.dbo.expense_procedure per elaborare i messaggi. La stored procedure viene eseguita con l'account dell'utente che ha eseguito l'istruzione CREATE QUEUE. La coda avvia al massimo 10 istanze della stored procedure.

CREATE QUEUE ExpenseQueue
    WITH STATUS = OFF,
      RETENTION = ON,
      ACTIVATION (
          PROCEDURE_NAME = AdventureWorks2008R2.dbo.expense_procedure,
          MAX_QUEUE_READERS = 10,
          EXECUTE AS SELF )
    ON [DEFAULT] ;

Vedere anche

Riferimento

ALTER QUEUE (Transact-SQL)

CREATE SERVICE (Transact-SQL)

DROP QUEUE (Transact-SQL)

RECEIVE (Transact-SQL)

EVENTDATA (Transact-SQL)

Concetti

Code

Creazione di applicazioni mediante Service Broker

Attivazione di Service Broker

Contesto di attivazione interna

Esercitazioni di Service Broker