Interface SzConfig

Namespace: Senzing.Sdk

Assembly: Senzing.Sdk.dll

Defines the C# interface that encapsulates and represents a Senzing configuration and provides functions to operate on that configuration.

public interface SzConfig

Examples

Create from template configuration:

// How to create an SzConfig instance representing the template configuration
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the SzConfigManager instance
    SzConfigManager configMgr = env.GetConfigManager();

    // create the config from the template
    SzConfig config = configMgr.CreateConfig();

    // do something with the SzConfig
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to create new SzConfig from the template.", e);
}

Create from configuration definition:

// How to create an SzConfig instance representing a specified config definition
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the SzConfigManager instance
    SzConfigManager configMgr = env.GetConfigManager();

    // obtain a JSON config definition (varies by application)
    string configDefinition = ReadConfigFile();

    // create the config using the config definition
    SzConfig config = configMgr.CreateConfig(configDefinition);

    // do something with the SzConfig
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to create a new SzConfig from a definition.", e);
}

Create from registered configuration ID:

// How to get a config definition by its configuration ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the config manager
    SzConfigManager configMgr = env.GetConfigManager();

    // get a valid configuration ID (will vary by application)
    long configID = configMgr.GetDefaultConfigID();

    // get the config definition for the config ID
    SzConfig config = configMgr.CreateConfig(configID);

    // do something with the SzConfig
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to Create SzConfig from config ID.", e);
}

Remarks

The Senzing config functions provide means to create, manipulate and export Senzing JSON configurations.

An SzConfig instance is typically obtained from an SzConfigManager instance via one of the following methods:

Methods

Export()

Retrieves the definition for this configuration.

string Export()

Returns

string: The configuration definition formatted as a JSON object.

Examples

Usage:

// How to export config JSON from a config handle
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the SzConfigManager instance
    SzConfigManager configMgr = env.GetConfigManager();

    // get an SzConfig object (varies by application)
    SzConfig config = configMgr.CreateConfig();

    // export the config
    string configDefinition = config.Export();
    demoResult = configDefinition; // @replace
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to export configuration.", e);
}

Example Result:
The example result is rather large, but can be viewed here (formatted for readability).

Remarks

NOTE: Typically, an implementations ToString() function will be implemented to return the result from this function.

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Register Data Sources

Code Snippet: Initialize Config

GetDataSourceRegistry()

Gets the data source registry for this configuration.

string GetDataSourceRegistry()

Returns

string: The data source registry describing the data sources for this configuration formatted as a JSON object.

Examples

Usage:

// How to get the data source registry from an in-memory config
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the SzConfigManager instance
    SzConfigManager configMgr = env.GetConfigManager();

    // get an SzConfig object (varies by application)
    SzConfig config = configMgr.CreateConfig();

    // get the data sources
    string registry = config.GetDataSourceRegistry();
    demoResult = registry; // @replace
    // do something with the returned JSON (e.g.: parse it and extract values)
    JsonObject? jsonObj = JsonNode.Parse(registry)?.AsObject();

    JsonArray? jsonArr = jsonObj?["DATA_SOURCES"]?.AsArray();

    // iterate over the data sources
    if (jsonArr != null)
    {
        for (int index = 0; index < jsonArr.Count; index++)
        {

            JsonObject? sourceObj = jsonArr[index]?.AsObject();

            string? dataSourceCode = sourceObj?["DSRC_CODE"]?.GetValue<string>();

            . . .
        }
    }

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to get data sources.", e);
}

Example Result: (formatted for readability)

{
  "DATA_SOURCES": [
    {
      "DSRC_ID": 1,
      "DSRC_CODE": "TEST"
    },
    {
      "DSRC_ID": 2,
      "DSRC_CODE": "SEARCH"
    }
  ]
}

Exceptions

SzException: If a failure occurs.

RegisterDataSource(string)

Adds a data source to this configuration.

string RegisterDataSource(string dataSourceCode)

Parameters

dataSourceCode string: The data source code for the new data source.

Returns

string: The JSON string describing the data source was registered.

Examples

Usage:

// How to register data sources with an in-memory config
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the SzConfigManager instance
    SzConfigManager configMgr = env.GetConfigManager();

    // get an SzConfig object (varies by application)
    SzConfig config = configMgr.CreateConfig();

    // add data sources to the config
    config.RegisterDataSource("CUSTOMERS");
    config.RegisterDataSource("EMPLOYEES");
    config.RegisterDataSource("WATCHLIST");

    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to add data sources.", e);
}

Example Result: (formatted for readability)

{
  "DSRC_ID": 1003
}

Remarks

Because SzConfig is an in-memory representation, the repository is not changed unless the configuration is exported and then registered via SzConfigManager.

An exception is thrown if the data source already exists in the configuration.

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Register Data Sources

UnregisterDataSource(string)

Removes a data source from this configuration.

void UnregisterDataSource(string dataSourceCode)

Parameters

dataSourceCode string: The data source code that identifies the data source to delete from the configuration.

Examples

Usage:

// How to unregister a data source from an in-memory config
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the SzConfigManager instance
    SzConfigManager configMgr = env.GetConfigManager();

    // get an SzConfig object (varies by application)
    SzConfig config = configMgr.CreateConfig();

    // delete the data source from the config
    config.UnregisterDataSource("CUSTOMERS");

    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to delete data source.", e);
}

Remarks

Because SzConfig is an in-memory representation, the repository is not changed unless the configuration is exported and then registered via SzConfigManager.

NOTE: This method is idempotent in that it succeeds with no changes being made when specifying a data source code that is not found in the registry.

WARNING: If records in the repository refer to the unregistered data source, the configuration cannot be used as the active configuration.

Exceptions

SzException: If a failure occurs.

Table of Contents

Interface SzConfig

Examples

Remarks

Methods

Export()

Returns

Examples

Remarks

Exceptions

GetDataSourceRegistry()

Returns

Examples

Exceptions

RegisterDataSource(string)

Parameters

Returns

Examples

Remarks

Exceptions

UnregisterDataSource(string)

Parameters

Examples

Remarks

Exceptions