Modelo de objeto de carga em massa XML do SQL Server (SQLXML 4.0)

O modelo de objeto de carregamento em massa XML do Microsoft SQL Server consiste no objeto SQLXMLBulkLoad. Esse objeto dá suporte aos métodos e propriedades a seguir.

Métodos

Executar
Em massa carrega os dados usando o arquivo de esquema e o arquivo de dados (ou fluxo) fornecidos como parâmetros.

Propriedades

BulkLoad
Especifica se uma carga em massa deve ser executada. Essa propriedade será útil se você quiser gerar apenas os esquemas (consulte as propriedades SchemaGen, SGDropTables e SGUseID a seguir) e não executar uma carga em massa. Esta é uma propriedade booliana. Quando a propriedade é definida como TRUE, o Carregamento em Massa XML é executado. Quando é definido como FALSE, o Carregamento em Massa XML não é executado.

O valor padrão é TRUE.

CheckConstraints
Especifica se as restrições (como restrições devido à relação chave primária/chave estrangeira entre colunas) especificadas na coluna devem ser verificadas quando a Carga em Massa XML insere dados nas colunas. Esta é uma propriedade booliana.

Quando a propriedade é definida como TRUE, o Carregamento em Massa XML verifica as restrições de cada valor inserido (o que significa que uma violação de restrição resulta em um erro).

Observação

Para deixar essa propriedade como FALSE, você deve ter permissões ALTER TABLE em tabelas de destino. Para obter mais informações, confira ALTER TABLE (Transact-SQL).

O valor padrão é FALSO. Quando é definido como FALSE, o Carregamento em Massa XML ignora as restrições durante uma operação de inserção. Na implementação atual, você deve definir as tabelas na ordem das relações de chave primária e chave estrangeira no esquema de mapeamento. Ou seja, uma tabela com uma chave primária deve ser definida antes da tabela correspondente com a chave estrangeira; caso contrário, a carga em massa XML falhará.

Observe que, se a Propagação de ID estiver sendo feita, essa opção não se aplicará e a verificação de restrição será deixada ativada. Isso ocorre quando KeepIdentity=False e há uma relação definida em que o pai é um campo de identidade e o valor é dado ao filho conforme ele é gerado.

ConnectionCommand
Identifica um objeto de conexão existente (por exemplo, o objeto de comando ADO ou ICommand) que o Carregamento em Massa XML deve usar. Você pode usar a propriedade ConnectionCommand em vez de especificar uma cadeia de conexão com a propriedade ConnectionString. A propriedade Transaction deve ser definida como TRUE se você usar ConnectionCommand.

Se você usar as propriedades ConnectionString e ConnectionCommand, o Carregamento em Massa XML usará a última propriedade especificada.

O valor padrão é NULL.

string de conexão
Identifica a cadeia de conexão OLE DB que fornece as informações necessárias para estabelecer uma conexão com uma instância do banco de dados. Se você usar as propriedades ConnectionString e ConnectionCommand, o Carregamento em Massa XML usará a última propriedade especificada.

O valor padrão é NULL.

ErrorLogFile
Especifica o nome do arquivo no qual o carregamento em massa XML registra erros e mensagens. O padrão é uma cadeia de caracteres vazia, caso em que nenhum registro em log ocorre.

FireTriggers
Especifica se os gatilhos definidos nas tabelas de destino devem ser acionados durante a operação carregamento em massa. O padrão é FALSE.

Quando definido como TRUE, os gatilhos serão acionados de acordo com o normal durante as operações de inserção.

Observação

Para deixar essa propriedade como FALSE, você deve ter permissões ALTER TABLE em tabelas de destino. Para obter mais informações, confira ALTER TABLE (Transact-SQL).

Observe que, se a Propagação de ID estiver sendo feita, essa opção não se aplicará e os gatilhos serão deixados ligados. Isso ocorre quando KeepIdentity=False e há uma relação definida em que o pai é um campo de identidade e o valor é dado ao filho conforme ele é gerado.

ForceTableLock
Especifica se as tabelas nas quais a carga em massa XML copia dados devem ser bloqueadas durante a carga em massa. Esta é uma propriedade booliana. Quando a propriedade é definida como TRUE, a carga em massa XML adquire bloqueios de tabela durante a carga em massa. Quando é definido como FALSE, o Carregamento em Massa XML adquire um bloqueio de tabela sempre que insere um registro em uma tabela.

O valor padrão é FALSO.

IgnoreDuplicateKeys
Especifica o que fazer se for feita uma tentativa de inserir valores duplicados em uma coluna de chave. Se essa propriedade for definida como TRUE e for feita uma tentativa de inserir um registro com um valor duplicado em uma coluna de chave, o SQL Server não inserirá esse registro. Mas ele insere o registro subsequente; portanto, a operação carregamento em massa não falha. Se essa propriedade estiver definida como FALSE, o Carregamento em Massa falhará quando for feita uma tentativa de inserir um valor duplicado em uma coluna de chave.

Quando a propriedade IgnoreDuplicateKeys é definida como TRUE, uma instrução COMMIT é emitida para cada registro inserido na tabela. Isso reduz o desempenho. A propriedade pode ser definida como TRUE somente quando a propriedade Transaction é definida como FALSE, porque o comportamento transacional é implementado usando arquivos.

O valor padrão é FALSO.

KeepIdentity
Especifica como lidar com os valores de uma coluna de tipo de identidade no arquivo de origem. Esta é uma propriedade booliana. Quando a propriedade é definida como TRUE, o Carregamento em Massa XML atribui os valores especificados no arquivo de origem à coluna de identidade. Quando a propriedade é definida como FALSE, a operação de carregamento em massa ignora os valores de coluna de identidade especificados na origem. Nesse caso, o SQL Server atribui um valor à coluna de identidade.

Se o Carregamento em Massa envolver uma coluna que é uma chave estrangeira que se refere a uma coluna de identidade na qual os valores gerados pelo SQL Server são armazenados, o Carregamento em Massa propaga adequadamente esses valores de identidade para a coluna de chave estrangeira.

O valor dessa propriedade se aplica a todas as colunas envolvidas na carga em massa. O valor padrão é TRUE.

Observação

Para deixar essa propriedade como TRUE, você deve ter permissões ALTER TABLE em tabelas de destino. Caso contrário, ele deverá ser definido como um valor de FALSE. Para obter mais informações, confira ALTER TABLE (Transact-SQL).

KeepNulls
Especifica qual valor usar para uma coluna que está faltando um atributo ou elemento filho correspondente no documento XML. Esta é uma propriedade booliana. Quando a propriedade é definida como TRUE, o Carregamento em Massa XML atribui um valor nulo à coluna. Ele não atribui o valor padrão da coluna, se houver, conforme definido no servidor. O valor dessa propriedade se aplica a todas as colunas envolvidas na carga em massa.

O valor padrão é FALSO.

SchemaGen
Especifica se as tabelas necessárias devem ser criadas antes de executar uma operação de carregamento em massa. Esta é uma propriedade booliana. Se essa propriedade for definida como TRUE, as tabelas identificadas no esquema de mapeamento serão criadas (o banco de dados deve existir). Se uma ou mais tabelas já existirem no banco de dados, a propriedade SGDropTables determinará se essas tabelas pré-existentes devem ser descartadas e recriadas.

O valor padrão da propriedade SchemaGen é FALSE. SchemaGen não cria restrições PRIMARY KEY nas tabelas recém-criadas. O SchemaGen, no entanto, criará restrições FOREIGN KEY no banco de dados se puder encontrar correspondências sql:relationship e sql:key-fields anotações no esquema de mapeamento e se o campo de chave consistir em uma única coluna.

Observe que, se você definir a propriedade SchemaGen como TRUE, o Carregamento em Massa XML fará o seguinte:

• Cria as tabelas necessárias com base nos nomes de elemento e atributo. Portanto, é importante que você não use palavras reservadas do SQL Server para nomes de elemento e atributo no esquema.

• Retorna dados de estouro para qualquer coluna designada usando o campo sql:overflow no formato de tipo de dados xml .

SGDropTables
Especifica se as tabelas existentes devem ser descartadas e recriadas. Você usa essa propriedade quando a propriedade SchemaGen é definida como TRUE. Se SGDropTables for FALSE, as tabelas existentes serão retidas. Quando essa propriedade é TRUE, as tabelas existentes são excluídas e recriadas.

O valor padrão é FALSO.

SGUseID
Especifica se o atributo no esquema de mapeamento identificado como id tipo pode ser usado na criação de uma restrição PRIMARY KEY quando a tabela é criada. Use essa propriedade quando a propriedade SchemaGen for definida como TRUE. Se SGUseID for TRUE, o utilitário SchemaGen usará um atributo para o qual dt:type="id" é especificado como a coluna de chave primária e adicionará a restrição PRIMARY KEY apropriada ao criar a tabela.

O valor padrão é FALSO.

TempFilePath
Especifica o caminho do arquivo em que a carga em massa XML cria os arquivos temporários para uma carga em massa transacionada. (Essa propriedade é útil somente quando a propriedade Transaction é definida como TRUE.) Você deve garantir que a conta do SQL Server usada para carregamento em massa XML tenha acesso a esse caminho. Se essa propriedade não estiver definida, o Carregamento em Massa XML armazenará os arquivos temporários no local especificado na variável de ambiente TEMP.

Transação
Especifica se o Carregamento em Massa deve ser feito como uma transação, caso em que a reversão é garantida se a carga em massa falhar. Esta é uma propriedade booliana. Se a propriedade for definida como TRUE, a carga em massa ocorrerá em um contexto transacional. A propriedade TempFilePath é útil somente quando Transaction é definido como TRUE.

Observação

Se você estiver carregando dados binários (como os tipos de dados bin.hex, bin.base64 XML para os tipos de dados binários e de imagem do SQL Server), a propriedade Transaction deverá ser definida como FALSE.

O valor padrão é FALSO.

XMLFragment
Especifica se os dados de origem são um fragmento XML. Um fragmento XML é um documento XML sem um único elemento de nível superior (raiz). Esta é uma propriedade booliana. Essa propriedade deve ser definida como TRUE se o arquivo de origem consistir em um fragmento XML.

O valor padrão é FALSO.