SqlConnection.RegisterColumnEncryptionKeyStoreProvidersOnConnection Method

Definition

Namespace:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Package:

Microsoft.Data.SqlClient v5.2.0

Registers the encryption key store providers on the SqlConnection instance. If this function has been called, any providers registered using the static RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) methods will be ignored. This function can be called more than once. This does shallow copying of the dictionary so that the app cannot alter the custom provider list once it has been set.

public:
 void RegisterColumnEncryptionKeyStoreProvidersOnConnection(System::Collections::Generic::IDictionary<System::String ^, Microsoft::Data::SqlClient::SqlColumnEncryptionKeyStoreProvider ^> ^ customProviders);

public void RegisterColumnEncryptionKeyStoreProvidersOnConnection (System.Collections.Generic.IDictionary<string,Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider> customProviders);

member this.RegisterColumnEncryptionKeyStoreProvidersOnConnection : System.Collections.Generic.IDictionary<string, Microsoft.Data.SqlClient.SqlColumnEncryptionKeyStoreProvider> -> unit

Public Sub RegisterColumnEncryptionKeyStoreProvidersOnConnection (customProviders As IDictionary(Of String, SqlColumnEncryptionKeyStoreProvider))

Parameters

customProviders

IDictionary<String,SqlColumnEncryptionKeyStoreProvider>

Dictionary of custom column encryption key providers

Exceptions

ArgumentNullException

A null dictionary was provided.

-or-

A string key in the dictionary was null or empty.

-or-

A SqlColumnEncryptionKeyStoreProvider value in the dictionary was null.

ArgumentException

A string key in the dictionary started with "MSSQL_". This prefix is reserved for system providers.

Remarks

Custom master key store providers can be registered with the driver at three different layers. The precedence of the three registrations is as follows:

• The per-command registration will be checked if it is not empty.
• If the per-command registration is empty, the per-connection registration will be checked if it is not empty.
• If the per-connection registration is empty, the global registration will be checked.

Once any key store provider is found at a registration level, the driver will NOT fall back to the other registrations to search for a provider. If providers are registered but the proper provider is not found at a level, an exception will be thrown containing only the registered providers in the registration that was checked.

The built-in column master key store providers that are available for the Windows Certificate Store, CNG Store and CSP are pre-registered.

This does shallow copying of the dictionary so that the app cannot alter the custom provider list once it has been set.