Connection String

Overview

A connection string describes how to open a data source or connect to a synchronization service. It can be specified as a text string, as a JSON object, or as a CSPro URI. CSPro uses a connection string to determine how to open or connect to a resource, generally a file or a server. A connection string contains a primary value that identifies the resource and optionally contains properties that are used when accessing the resource. Properties typically have a property value associated with each property name.

CSPro can implicitly calculate the types of most resources. For example, the extension of "Popstan.csdb" indicates that this connection string references a CSPro DB data source, and "Dropbox" indicates a reference to a Dropbox synchronization service.

For more information on connection strings, including implicit type calculations, see:

Connection Strings Specified as Text

A connection string, specified as a text string, is made up of several components:

resource|property_name1=property_value1&property_name2=property_value2

The resource argument is generally the file name of a data source or the URL of a synchronization service. File names can be specified as relative or absolute paths. If only the resource is specified, then the connection string is complete. However, if any properties are specified, then the properties must be separated from the resource with a pipe '|' character.

Multiple properties can be specified, with each grouping separated by the ampersand '&' character. The property name is listed, followed by an equals '=' sign, and then the property value is given. Most properties must be specified as name–value pairs, but some properties can be defined simply by defining the name.

Most property values can be defined in human-readable text, but if the value contains special characters such as '&' or '=' characters, it must be percent-encoded. You can encode such strings using the String Encoder, or dynamically percent-encode strings in logic using the encode function with the PercentEncoding argument.

The following are examples of data connection strings specified using text:

C:\cspro-projects\data\body-measurements.csdb

C:\cspro-projects\data\body-measurements.csdbe|password=MyPa%24%24w0rd%21

../data/body-measurements.json|verbose&binaryDataFormat=dataUrl

The following are examples of synchronization connection strings specified using text:

https://example.org/csweb/api

Dropbox|email=jackw%40example.org

Using arguments not known at runtime, the following logic shows how to use encode to ensure that property values are percent-encoded as shown in the examples above:

maketext(@"C:\cspro-projects\data\body-measurements.csdbe|password=%s",
encode(PercentEncoding, "MyPa$$w0rd!"));

maketext("Dropbox|email=%s",
encode(PercentEncoding, "jackw@example.org"));

Connection Strings Specified as JSON

In contexts where CSPro is parsing JSON, a value specified as a JSON string will be parsed as a text-based connection string. However, if a JSON object is provided, it is parsed using different rules. The resource must be specified using the name "path" or "url". When using "path", generally intended for data connection strings the path can be specified as a relative or absolute path. Optional properties are specified as JSON strings. The property values do not need to be percent-encoded but instead should be encoded properly using rules for JSON strings.

The following shows the above data connection strings specified using JSON:

{
"path": "C:\\cspro-data\\body-measurements.csdb"
}

{
"path": "C:\\cspro-data\\body-measurements.csdbe",
"password": "MyPa$$w0rd!"
}

{
"path": "../data/body-measurements.json",
"verbose": true,
"binaryDataFormat": "dataUrl"
}

The following shows the above synchronization connection strings specified using JSON:

{
"url": "https://example.org/csweb/api"
}

{
"url": "Dropbox",
"email": "jackw@example.org"
}

Connection Strings Specified as CSPro URIs

Connection strings can also be specified as CSPro URIs. The URI path contains the type, either /data or /sync, followed by the resource, specified as a path. Optional properties are specified as part of a query string. More details are available here.

The following shows the above data connection strings specified as CSPro URIs:

cspro:///data/C:/cspro-projects/data/body-measurements.csdb

cspro:///data/C:/cspro-projects/data/body-measurements.csdbe?password=MyPa%24%24w0rd%21

cspro:///data/../data/body-measurements.json?verbose&binaryDataFormat=dataUrl

The following shows the above synchronization connection strings specified as CSPro URIs:

cspro:///sync/https://example.org/csweb/api

cspro:///sync/Dropbox?email=jackw%40example.org