sz-sdk-csharp

If you are beginning your journey with Senzing, please start with Senzing Quick Start guides.

Overview

The Senzing C# SDK provides the C# interface to the native Senzing SDK's. This repository is dependent on the Senzing native shared library (.so, .dylib or .dll) that is part of the Senzing product and function without it.

While this SDK is being made available as open source, the actual Senzing.Sdk NuGet package file (Senzing.Sdk.4.0.0.nupkg) that you use should be obtained from Senzing product installation to ensure that the C# code version matches the native library version.

Prerequisites

1. Microsoft .NET for your platform: https://dotnet.microsoft.com/en-us/download

2. Senzing v4.0 or later (for running unit tests)

3. Set the SENZING_PATH environment variable:

   • Linux: export SENZING_PATH=/opt/senzing
   • macOS: export SENZING_PATH=$HOME/senzing
   • Windows: set SENZING_PATH=%USERPROFILE%\senzing

4. Set your library path appropriately for Senzing libraries:

   • Linux: Set the LD_LIBRARY_PATH:

     export LD_LIBRARY_PATH=/opt/senzing/er/lib:$LD_LIBRARY_PATH

   • macOS: Set DYLD_LIBRARY_PATH:

     export DYLD_LIBRARY_PATH=/Library/Senzing/er/lib:/Library/Senzing/er/lib/macos:$DYLD_LIBRARY_PATH

   • Windows: Set Path:

     set Path=C:\Senzing\er\lib;%Path%

Building

1. Generating the Example Documentation Snippets

   dotnet test Senzing.Sdk.Demo -p:GeneratePackageOnBuild=false

   Alternatively, via Makefile:

   gmake demo

2. Building with Debug:

   dotnet build Senzing.Sdk -p:GenerateDocumentationFile=true

   NOTE: This will produce warnings if you have NOT generated the example documentation snippets.

   Alternatively, via Makefile it will always generate the documentation example snippets first:

   gmake debug

   The DLL will be found in Senzing.Sdk/bin/Debug/netstandard2.0/Senzing.Sdk.dll The NuGet package will be found in Senzing.Sdk/bin/Debug/Senzing.Sdk.4.0.0.nupkg

3. Building with Release:

   dotnet build -c Release Senzing.Sdk -p:GenerateDocumentationFile=true

   Alternatively, via Makefile it will always generate the documentation example snippets first:

   gmake release

   NOTE: This will produce warnings if you have NOT generated the example documentation snippets.

   The DLL will be found in Senzing.Sdk/bin/Release/netstandard2.0/Senzing.Sdk.dll The NuGet package will be found in Senzing.Sdk/bin/Release/Senzing.Sdk.4.0.0.nupkg

4. Running unit tests:

   dotnet test Senzing.Sdk.Tests

   Alternatively, via Makefile:

   gmake release

5. Verifying the code formatting:

   dotnet format --verify-no-changes --verbosity diagnostic Senzing.Sdk
   dotnet format --verify-no-changes --verbosity diagnostic Senzing.Sdk.Tests
   dotnet format --verify-no-changes --verbosity diagnostic Senzing.Sdk.Demo

   Alternative, via Makefile:

   gmake format

   Or for each module individually:

   gmake format-sdk
   gmake format-test
   gmake format-demo

6. Generate documentation:

   dotnet docfx docfx.json

   Alternatively, via Makefile:

   gmake docs

   The generated documentation will reside in target/apidocs/_site/

7. Clean up build artifacts:

   dotnet clean Senzing.Sdk
   dotnet clean -c Release Senzing.Sdk
   dotnet clean Senzing.Sdk.Tests
   dotnet clean Senzing.Sdk.Demo
   rm -rf Senzing.Sdk/bin
   rm -rf Senzing.Sdk/obj
   rm -rf Senzing.Sdk.Tests/bin
   rm -rf Senzing.Sdk.Tests/obj
   rm -rf Senzing.Sdk.Demo/bin
   rm -rf Senzing.Sdk.Demo/obj
   rm -rf target

   Alternative, via Makefile:

   gmake clean

Usage

1. Create and configure a local NuGet repository:

   mkdir [path]
   dotnet nuget add source [path] -n [local-source-name]

   • Example (macOS / Linux):

     mkdir -p ~/dev/nuget/packages
     dotnet nuget add source ~/dev/nuget/packages -n dev

   • Example (Windows):

     mkdir %USERPROFILE%\dev\nuget\packages
     dotnet nuget add source %USERPROFILE%\dev\nuget\packages -n dev

2. Push the Senzing.Sdk NuGet package from your Senzing distribution to your local repository:

   dotnet nuget push [path-to-Senzing.Sdk.4.0.0.nupkg] --source [local-source-name]

   • Example (macOS / Linux):

     dotnet nuget push /opt/senzing/er/sdk/dotnet/Senzing.Sdk.4.0.0.nupkg --source dev

   • Example (Windows):

     dotnet nuget push %USERPROFILE%\Senzing\er\sdk\dotnet\Senzing.Sdk.4.0.0.nupkg --source dev

3. Add the Senzing.Sdk NuGet package as a dependency to your project:

   • OPTION 1: Add the latest pre-release version of Senzing.Sdk as your dependency:

     dotnet add [your-project-name] package Senzing.Sdk --prerelease

   • OPTION 2: Add a specific version of Senzing.Sdk as your dependency:

     dotnet add [your-project-name] package Senzing.Sdk --version 4.0.0

   • OPTION 3: Add the latest production version of Senzing.Sdk as your dependency (note: this will only function once Senzing.Sdk v4.0.0 is released):

     dotnet add [your-project-name] package Senzing.Sdk

Using Example Code

Senzing encourages and allows you to freely copy the provided example code and modify it to your own needs as you see fit. However, please refer to the Global Suppression Notes to understand how to best adapt the example code to your own coding project.