Modello a oggetti per il caricamento bulk XML di SQL Server (SQLXML 4.0)

Si applica a: SQL Server Azure SQL Database

Il modello a oggetti Load bulk XML di Microsoft SQL Server è costituito dall'oggetto SQLXMLBulkLoad. Questo oggetto supporta i metodi e le proprietà seguenti.

Metodi

Esecuzione
Esegue il caricamento bulk dei dati utilizzando il file dello schema e il file di dati (o flusso) forniti come parametri.

Proprietà

BulkLoad
Specifica se deve essere eseguito un caricamento bulk. Questa proprietà è utile se si desidera generare solo gli schemi (vedere le proprietà SchemaGen, SGDropTables e SGUseID che seguono) e non eseguire un carico bulk. Si tratta di una proprietà booleana. Quando la proprietà è impostata su TRUE, viene eseguito il caricamento bulk XML. Quando la proprietà è impostata su FALSE, il caricamento bulk XML non viene eseguito.

Il valore predefinito è TRUE.

CheckConstraints
Specifica se i vincoli (ad esempio vincoli dovuti alla relazione di chiave primaria/chiave esterna fra colonne) specificati nella colonna devono essere controllati quando il caricamento bulk XML inserisce dati nelle colonne. Si tratta di una proprietà booleana.

Quando la proprietà è impostata su TRUE, il caricamento bulk XML controlla i vincoli per ogni valore inserito. Di conseguenza, la violazione di un vincolo produce un errore.

Nota

Per lasciare questa proprietà come FALSE, è necessario disporre delle autorizzazioni ALTER TABLE per le tabelle di destinazione. Per altre informazioni, vedere ALTER TABLE (Transact-SQL).

Il valore predefinito è FALSE. Quando la proprietà è impostata su FALSE, il caricamento bulk XML ignora i vincoli durante un'operazione di inserimento. Nell'implementazione corrente è necessario definire le tabelle nell'ordine delle relazioni di chiave primaria/chiave esterna nello schema di mapping. Di conseguenza, una tabella con una chiave primaria deve essere definita prima della tabella corrispondente contenente la chiave esterna. In caso contrario, il caricamento bulk XML restituisce un errore.

Si noti che se viene eseguita la propagazione degli ID, questa opzione non viene applicata e il controllo dei vincoli resta attivato. Ciò si verifica quando KeepIdentity=False ed è presente una relazione definita in cui il padre è un campo di identità e il valore viene assegnato al figlio non appena generato.

ConnectionCommand
Identifica un oggetto di connessione esistente, ad esempio l'oggetto comando ADO o ICommand, che deve essere usato da Caricamento bulk XML. È possibile usare la proprietà ConnectionCommand anziché specificare una stringa di connessione con la proprietà ConnectionString. La proprietà Transaction deve essere impostata su TRUE se si usa ConnectionCommand.

Se si usano sia le proprietà ConnectionString che ConnectionCommand, il caricamento bulk XML usa l'ultima proprietà specificata.

Il valore predefinito è NULL.

ConnectionString
Identifica la stringa di connessione OLE DB che fornisce le informazioni necessarie per stabilire una connessione a un'istanza del database. Se si usano sia le proprietà ConnectionString che ConnectionCommand, il caricamento bulk XML usa l'ultima proprietà specificata.

Il valore predefinito è NULL.

ErrorLogFile
Specifica il nome del file in cui vengono registrati errori e messaggi dal caricamento bulk XML. Il valore predefinito è una stringa vuota, a indicare che non viene eseguita alcuna registrazione.

FireTriggers
Specifica se i trigger definiti nelle tabelle di destinazione devono essere attivati durante l'operazione di caricamento bulk. Il valore predefinito è FALSE.

Quando la proprietà è impostata su TRUE, i trigger vengono attivati normalmente durante le operazioni di inserimento.

Nota

Per lasciare questa proprietà come FALSE, è necessario disporre delle autorizzazioni ALTER TABLE per le tabelle di destinazione. Per altre informazioni, vedere ALTER TABLE (Transact-SQL).

Si noti che se viene eseguita la propagazione degli ID, questa opzione non viene applicata e i trigger restano attivati. Ciò si verifica quando KeepIdentity=False ed è presente una relazione definita in cui il padre è un campo di identità e il valore viene assegnato al figlio non appena generato.

ForceTableLock
Specifica se le tabelle in cui vengono copiati i dati tramite il caricamento bulk XML devono essere bloccate per la durata del caricamento bulk stesso. Si tratta di una proprietà booleana. Quando questa proprietà è impostata su TRUE, il caricamento bulk XML acquisisce blocchi di tabella per la durata del caricamento bulk stesso. Quando la proprietà è impostata su FALSE, il caricamento bulk XML acquisisce un blocco di tabella ogni volta che inserisce un record in una tabella.

Il valore predefinito è FALSE.

IgnoreDuplicateKeys
Specifica l'operazione da effettuare se viene eseguito un tentativo di inserimento di valori duplicati in una colonna chiave. Se questa proprietà è impostata su TRUE e viene effettuato un tentativo di inserire un record con un valore duplicato in una colonna chiave, SQL Server non inserisce tale record. Viene invece inserito il record successivo. L'operazione di caricamento bulk, pertanto, non ha esito negativo. Se la proprietà è impostata su FALSE, il caricamento bulk non riesce quando viene eseguito un tentativo di inserimento di un valore duplicato in una colonna chiave.

Quando la proprietà IgnoreDuplicateKeys è impostata su TRUE, viene emessa un'istruzione COMMIT per ogni record inserito nella tabella. Questo comportamento provoca una riduzione delle prestazioni. La proprietà può essere impostata su TRUE solo quando la proprietà Transaction è impostata su FALSE, perché il comportamento transazionale viene implementato usando i file.

Il valore predefinito è FALSE.

KeepIdentity
Specifica la modalità di gestione dei valori per una colonna di tipo Identity nel file di origine. Si tratta di una proprietà booleana. Quando la proprietà è impostata su TRUE, il caricamento bulk XML assegna i valori specificati nel file di origine alla colonna Identity. Quando la proprietà è impostata su FALSE, l'operazione di caricamento bulk ignora i valori di colonna di tipo Identity specificati nell'origine. In questo caso, SQL Server assegna un valore alla colonna identity.

Se il carico bulk implica una colonna che fa riferimento a una chiave esterna che fa riferimento a una colonna identity in cui vengono archiviati valori generati SQL Server, il caricamento bulk propaga in modo appropriato questi valori di identità alla colonna chiave esterna.

Il valore di questa proprietà si applica a tutte le colonne interessate dal caricamento bulk. Il valore predefinito è TRUE.

Nota

Per lasciare questa proprietà come TRUE, è necessario disporre delle autorizzazioni ALTER TABLE nelle tabelle di destinazione. In caso contrario, la proprietà deve essere impostata sul valore FALSE. Per altre informazioni, vedere ALTER TABLE (Transact-SQL).

KeepNulls
Specifica il valore da utilizzare per una colonna in cui manca un attributo corrispondente o un elemento figlio nel documento XML. Si tratta di una proprietà booleana. Quando la proprietà è impostata su TRUE, il caricamento bulk XML assegna un valore Null alla colonna. Non viene assegnato il valore predefinito della colonna, se presente, in base all'impostazione nel server. Il valore di questa proprietà si applica a tutte le colonne interessate dal caricamento bulk.

Il valore predefinito è FALSE.

SchemaGen
Specifica se creare le tabelle necessarie prima di eseguire un'operazione di caricamento bulk. Si tratta di una proprietà booleana. Se questa proprietà è impostata su TRUE, vengono create le tabelle identificate nello schema di mapping (il database deve essere presente). Se esiste già una o più tabelle nel database, la proprietà SGDropTables determina se queste tabelle preesistenti devono essere eliminate e ricreate.

Il valore predefinito per la proprietà SchemaGen è FALSE. SchemaGen non crea vincoli PRIMARY KEY nelle tabelle appena create. SchemaGen crea tuttavia vincoli FOREIGN KEY nel database se può trovare le annotazioni sql:relationship e sql:key-fields nello schema di mapping e se il campo chiave è costituito da una singola colonna.

Si noti che se si imposta la proprietà SchemaGen su TRUE, il caricamento bulk XML esegue le operazioni seguenti:

• Vengono create le tabelle necessarie dai nomi di elemento e di attributo. È quindi importante non usare SQL Server parole riservate per i nomi di elementi e attributi nello schema.

• Restituisce i dati di overflow per qualsiasi colonna designata usando il formato sql:overflow-field nel formato del tipo di dati xml .

SGDropTables
Specifica se le tabelle esistenti devono essere eliminate e ricreate. Questa proprietà viene usata quando la proprietà SchemaGen è impostata su TRUE. Se SGDropTables è FALSE, le tabelle esistenti vengono mantenute. Quando questa proprietà è TRUE, le tabelle esistenti vengono eliminate e ricreate.

Il valore predefinito è FALSE.

SGUseID
Specifica se l'attributo nello schema di mapping identificato come tipo id può essere usato nella creazione di un vincolo PRIMARY KEY quando viene creata la tabella. Utilizzare questa proprietà quando la proprietà SchemaGen è impostata su TRUE. Se SGUseID è TRUE, l'utilità SchemaGen usa un attributo per cui dt:type="id" viene specificato come colonna chiave primaria e aggiunge il vincolo PRIMARY KEY appropriato durante la creazione della tabella.

Il valore predefinito è FALSE.

TempFilePath
Specifica il percorso del file in cui il caricamento bulk XML crea i file temporanei per un caricamento bulk in transazioni. Questa proprietà è utile solo quando la proprietà Transaction è impostata su TRUE. È necessario assicurarsi che l'account SQL Server usato per il caricamento bulk XML abbia accesso a questo percorso. Se questa proprietà non è impostata, il caricamento bulk XML archivia i file temporanei nel percorso specificato nella variabile di ambiente TEMP.

Transazione
Specifica se il caricamento bulk deve essere eseguito come transazione. In questo caso, è garantito il rollback se il caricamento bulk ha esito negativo. Si tratta di una proprietà booleana. Se la proprietà è impostata su TRUE, il caricamento bulk viene eseguito in un contesto transazionale. La proprietà TempFilePath è utile solo quando Transaction è impostato su TRUE.

Nota

Se si caricano dati binari, ad esempio bin.hex, bin.base64 tipi di dati XML nel file binario, immagine SQL Server tipi di dati, la proprietà Transaction deve essere impostata su FALSE.

Il valore predefinito è FALSE.

XMLFragment
Specifica se i dati di origine sono un frammento XML. Un frammento XML è un documento XML privo di singolo elemento di livello principale (radice). Si tratta di una proprietà booleana. Questa proprietà deve essere impostata su TRUE se il file di origine è costituito da un frammento XML.

Il valore predefinito è FALSE.