Chiola.AseClient.StrongName 0.20.1

Chiola.AseClient

This is a fork of DataAction/AdoNetCore.AseClient, a .NET data provider for SAP/Sybase ASE originally created and maintained by DataAction and its contributors. All credit for the original TDS protocol implementation goes to them — see LICENSE (Apache-2.0, preserved from upstream).

Why this fork exists: built as the driver dependency for Chiola.EntityFrameworkCore.Ase, a from-scratch EF Core provider for SAP ASE. Several real bugs and gaps in the upstream driver were found and worked around while building that provider (see its DECISIONS.md) — this fork exists to fix them directly at the source instead of accumulating workarounds downstream.

What changed from upstream (see DECISIONS.md for the full history and reasoning behind each of these):

• Targets net5.0–net9.0 in addition to upstream's full legacy matrix (netcoreapp1.0 through netstandard2.0/net46). The fork briefly dropped everything but net9.0 (its only consumer at the time), then restored the original matrix so this package can benefit anyone still on an older target, not just this fork's own use case — net5.0–net9.0 were added on top, not swapped in, closing the gap between upstream's newest target (2019) and modern .NET.
• Dropped the AdoNetCore.AseClient.Benchmark project (outdated BenchmarkDotNet 0.10.14, not relevant to this fork's goal) — AdoNetCore.AseClient.StrongName was kept (restored alongside the target matrix).
• Test project pinned to NUnit 3.x (upstream's actual test suite, ~1200 unit tests + a real integration suite against live ASE) rather than upgrading to NUnit 4 outright, to avoid churn from its CollectionAssert/StringAssert namespace move — revisit later if worth it. The test project itself only runs against net9.0 today (not the full matrix like src/) — see CLAUDE.md.
• Real bug fixes (see DECISIONS.md for each): AseConnection.ClearPool()/ClearPools() were literal no-ops upstream (//todo: implement) — implemented for real via a pool-generation pattern. Added proactive idle-connection eviction to the pool (previously only checked lazily, when a connection was next reserved — a pool that went idle just stayed open on the server forever).

Package published as Chiola.AseClient / Chiola.AseClient.StrongName on NuGet (not AdoNetCore.AseClient, to avoid clashing with the upstream package).

A .NET data provider for SAP ASE — fork of DataAction/AdoNetCore.AseClient.

SAP (formerly Sybase) has supported accessing the ASE database management system from ADO.NET for many years. Unfortunately SAP has not yet made a driver available to support .NET Core, so this project enables product teams that are dependent upon ASE to keep moving their application stack forwards.

The current .NET 4 version of SAP's Sybase.Data.AseClient driver is a .NET Framework managed wrapper around SAP's unmanged ADO DB provider and is dependent upon COM. COM is a Windows-only technology and will never be available to .NET Core, making it difficult to port the existing SAP driver.

Under the hood, ASE (and Microsoft Sql Server for that matter) relies on an application-layer protocol called Tabular Data Stream to transfer data between the database server and the client application. ASE uses TDS 5.0.

This project provides a .NET Core native implementation of the TDS 5.0 protocol via an ADO.NET DB Provider, making SAP ASE accessible from .NET Core applications hosted on Windows, Linux, Docker and also serverless platforms like AWS Lambda.

Table of Contents

• Downloads
• Objectives
• Performance benchmarks
• Connection strings
• Supported types
• Code samples

Downloads

The latest stable release of the AdoNetCore.AseClient is available on NuGet.

Objectives

• Functional parity with the Sybase.Data.AseClient provided by SAP. Ideally, our driver will be a drop in replacement for the Sybase.Data.AseClient (with some namespace changes). The following types are supported:

  • AseClientFactory - .NET Core 2.1+
  • AseCommand
  • AseCommandBuilder
  • AseConnection
  • AseConnectionPool
  • AseConnectionPoolManager
  • AseDataAdapter
  • AseDataReader
  • AseDbType
  • AseDecimal
  • AseError
  • AseErrorCollection
  • AseException
  • AseInfoMessageEventArgs
  • AseInfoMessageEventHandler
  • AseParameter
  • AseParameterCollection
  • AseRowUpdatedEventArgs - .NET Core 2.0+
  • AseRowUpdatedEventHandler - .NET Core 2.0+
  • AseRowUpdatingEventArgs - .NET Core 2.0+
  • AseRowUpdatingEventHandler - .NET Core 2.0+
  • TraceEnterEventHandler
  • TraceExitEventHandler

• Not all features are currently supported, and some features will not be supported. Refer to upstream's Unsupported features wiki page (still applicable — this fork hasn't diverged on feature support yet).

• Performance equivalent to or better than that of Sybase.Data.AseClient provided by SAP. This is possible as we are eliminating the COM and OLE DB layers from this driver and .NET Core is fast.

• Target all of upstream's frameworks (netcoreapp1.0 through netstandard2.0/net46) plus net5.0–net9.0.

• Should work with Dapper at least as well as the Sybase.Data.AseClient

Performance benchmarks

The benchmark project (AdoNetCore.AseClient.Benchmark) and its historical results against Sybase.Data.AseClient were dropped in this fork (see the fork notice above) — not relevant to this fork's goal of serving Chiola.EntityFrameworkCore.Ase. See upstream's README for the original methodology and results.

Connection strings

connectionstrings.com lists the following connection string properties for the ASE ADO.NET Data Provider. In keeping with our objective of being a drop-in replacement for the Sybase.Data.AseClient, we aim to use identical connection string syntax to the Sybase.Data.AseClient, however our support for the various properties will be limited. Our support is as follows:

Supported types

Types supported when sending requests to the database

Types supported when reading responses from the database

Code samples

Open a database connection

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using(var connection = new AseConnection(connectionString))
{
    connection.Open();

    // use the connection...
}

Execute a SQL statement and read response data

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString))
{
    connection.Open();

    using (var command = connection.CreateCommand())
    {
        command.CommandText = "SELECT FirstName, LastName FROM Customer";

        using (var reader = command.ExecuteReader())
        {
            // Get the results.
            while (reader.Read())
            {
                var firstName = reader.GetString(0);
                var lastName = reader.GetString(1);

                // Do something with the data...
            }
        }
    }
}

Execute a SQL statement that returns no results

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString))
{
    connection.Open();

    using (var command = connection.CreateCommand())
    {
        command.CommandText = "INSERT INTO Customer (FirstName, LastName) VALUES ('Fred', 'Flintstone')";

        var recordsModified = command.ExecuteNonQuery();
    }
}

Execute a SQL statement that returns a scalar value

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString))
{
    connection.Open();

    using (var command = connection.CreateCommand())
    {
        command.CommandText = "SELECT COUNT(*) FROM Customer";

        var result = command.ExecuteScalar();
    }
}

Use input parameters with a SQL query

Note: ASE only allows Output, InputOutput, and ReturnValue parameters with stored procedures

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString)
{
    connection.Open();

    using (var command = connection.CreateCommand())
    {
        command.CommandText = "SELECT TOP 1 FirstName FROM Customer WHERE LastName = @lastName";

        command.Parameters.AddWithValue("@lastName", "Rubble");

        var result = command.ExecuteScalar();
    }
}

Execute a stored procedure and read response data

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString)
{
    connection.Open();

    using (var command = connection.CreateCommand())
    {
        command.CommandText = "GetCustomer";
        command.CommandType = CommandType.StoredProcedure;

        command.Parameters.AddWithValue("@lastName", "Rubble");

        using (var reader = command.ExecuteReader())
        {
            // Get the results.
            while (reader.Read())
            {
                var firstName = reader.GetString(0);
                var lastName = reader.GetString(1);

                // Do something with the data...
            }
        }
    }
}

Execute a stored procedure that returns no results

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString))
{
    connection.Open();

    using (var command = connection.CreateCommand())
    {
        command.CommandText = "CreateCustomer";
        command.CommandType = CommandType.StoredProcedure;

        command.Parameters.AddWithValue("@firstName", "Fred");
        command.Parameters.AddWithValue("@lastName", "Flintstone");

        command.ExecuteNonQuery();
    }
}

Execute a stored procedure that returns a scalar value

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString))
{
    connection.Open();

    using (var command = connection.CreateCommand())
    {
        command.CommandText = "CountCustomer";
        command.CommandType = CommandType.StoredProcedure;

        var result = command.ExecuteScalar();
    }
}

Use input, output, and return parameters with a stored procedure

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString))
{
    connection.Open();

    using (var command = connection.CreateCommand())
    {
        command.CommandText = "GetCustomerFirstName";
        command.CommandType = CommandType.StoredProcedure;

        command.Parameters.AddWithValue("@lastName", "Rubble");

        var outputParameter = command.Parameters.Add("@firstName", AseDbType.VarChar);
        outputParameter.Direction = ParameterDirection.Output;

        var returnParameter = command.Parameters.Add("@returnValue", AseDbType.Integer);
        returnParameter.Direction = ParameterDirection.ReturnValue;

        command.ExecuteNonQuery();

        //Do something with outputParameter.Value and returnParameter.Value...
    }
}

Execute a stored procedure and read response data with Dapper

var connectionString = "Data Source=myASEserver;Port=5000;Database=myDataBase;Uid=myUsername;Pwd=myPassword;";

using (var connection = new AseConnection(connectionString))
{
    connection.Open();

    var barneyRubble = connection.Query<Customer>("GetCustomer", new {lastName = "Rubble"}, commandType: CommandType.StoredProcedure).First();

    // Do something with the result...
}