Installation

Get the VECU Custody .NET SDK installed and configured in your project.

Prerequisites

• .NET 8.0 or .NET 10 SDK
• NuGet package manager
• Cox Automotive Artifactory access

Step 1: Configure NuGet Source

The SDK is hosted in Cox Automotive's private Artifactory. Configure NuGet to access it.

Option A: nuget.config (Recommended)

Create or update nuget.config in your solution root:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="cai-artifactory" value="https://artifactory.coxautoinc.com/artifactory/api/nuget/cai-nuget" />
  </packageSources>
  <packageSourceCredentials>
    <cai-artifactory>
      <add key="Username" value="%NUGET_ARTIFACTORY_USER%" />
      <add key="ClearTextPassword" value="%NUGET_ARTIFACTORY_TOKEN%" />
    </cai-artifactory>
  </packageSourceCredentials>
</configuration>

Set environment variables for authentication:

# Linux/macOS
export NUGET_ARTIFACTORY_USER="your-username"
export NUGET_ARTIFACTORY_TOKEN="your-token"

# Windows (PowerShell)
$env:NUGET_ARTIFACTORY_USER="your-username"
$env:NUGET_ARTIFACTORY_TOKEN="your-token"

# Windows (Command Prompt)
set NUGET_ARTIFACTORY_USER=your-username
set NUGET_ARTIFACTORY_TOKEN=your-token

Option B: .NET CLI

Add the source using the .NET CLI:

dotnet nuget add source "https://artifactory.coxautoinc.com/artifactory/api/nuget/cai-nuget" \
  --name "cai-artifactory" \
  --username "$NUGET_ARTIFACTORY_USER" \
  --password "$NUGET_ARTIFACTORY_TOKEN" \
  --store-password-in-clear-text

Option C: Visual Studio

1. Tools → Options → NuGet Package Manager → Package Sources
2. Click + to add a new source
3. Name: cai-artifactory
4. Source: https://artifactory.coxautoinc.com/artifactory/api/nuget/cai-nuget
5. Click Update, then OK

For authentication, Visual Studio will prompt for credentials when accessing the source.

Step 2: Install the SDK

dotnet add package CoxAuto.Vecu.CustodySdk

Step 3: Verify Installation

Create a simple test to verify the SDK is installed correctly:

using CoxAuto.Vecu.CustodySdk.Client;
using CoxAuto.Vecu.CustodySdk.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddCustodyClient(options =>
{
    options.Environment = CustodyEnvironment.Sandbox;
    options.UseMockData = true; // No real API calls for verification
});

var serviceProvider = services.BuildServiceProvider();
var client = serviceProvider.GetRequiredService<ICustodyServiceClient>();

Console.WriteLine($"SDK installed successfully!");
Console.WriteLine($"Client type: {client.GetType().Name}");

Run the verification:

dotnet run

Expected output:

SDK installed successfully!
Client type: CustodyServiceClient

Environment Variables

The SDK supports configuration via environment variables:

Project Structure Example

A typical project setup:

my-project/
├── src/
│   ├── MyProject/
│   │   ├── Program.cs
│   │   ├── appsettings.json
│   │   ├── appsettings.Development.json
│   │   └── MyProject.csproj
│   └── MyProject.Tests/
│       └── MyProject.Tests.csproj
├── nuget.config
└── MyProject.sln

Example appsettings.json:

{
  "CustodyClient": {
    "Environment": "Sandbox",
    "TimeoutSeconds": 30,
    "MaxRetries": 3
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "CoxAuto.Vecu.CustodySdk": "Debug"
    }
  }
}

Example appsettings.Development.json:

{
  "CustodyClient": {
    "EnableDetailedLogging": true
  }
}

Example .csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <!-- Target .NET 8.0 (LTS) or .NET 10 -->
    <TargetFramework>net8.0</TargetFramework>
    <!-- <TargetFramework>net10.0</TargetFramework> -->
    <UserSecretsId>your-user-secrets-id</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="CoxAuto.Vecu.CustodySdk" Version="1.2.0" />
  </ItemGroup>
</Project>

User Secrets (Development)

For local development, use .NET user secrets to store credentials used by your TokenProvider callback:

# Initialize user secrets
dotnet user-secrets init

# Store credentials your TokenProvider uses (example)
dotnet user-secrets set "Auth:ClientId" "your-client-id"
dotnet user-secrets set "Auth:ClientSecret" "your-client-secret"

Then reference these in your TokenProvider callback:

builder.Services.AddCustodyClient(options =>
{
    options.Environment = CustodyEnvironment.Sandbox;
    options.TokenProvider = async (ct) =>
    {
        var clientId = builder.Configuration["Auth:ClientId"];
        var clientSecret = builder.Configuration["Auth:ClientSecret"];
        return await GetTokenAsync(clientId, clientSecret, ct);
    };
});

Troubleshooting

Package Not Found

If NuGet cannot find the package:

1. Verify Artifactory URL is correct in nuget.config
2. Check authentication credentials are set in environment variables
3. Clear NuGet cache and retry:

dotnet nuget locals all --clear
dotnet restore

1. Test Artifactory access:

dotnet nuget list source

NuGet Authentication Errors

If you see 401 Unauthorized errors:

1. Verify credentials are correct:

   echo $NUGET_ARTIFACTORY_USER
   echo $NUGET_ARTIFACTORY_TOKEN
   

2. Ensure credentials are not expired

3. Check you have read access to the nuget-release-local repository in Artifactory

SSL Certificate Errors

If you encounter SSL errors on corporate networks:

# Trust the Artifactory certificate (use with caution)
dotnet nuget update source cai-artifactory --source "https://artifactory.coxautoinc.com/artifactory/api/nuget/cai-nuget" --valid-authentication-types basic

Or configure your system to trust the corporate CA certificate.

Version Conflicts

If you have dependency conflicts:

1. Check for conflicting package versions:

   dotnet list package --include-transitive
   

2. Update all packages to compatible versions:

   dotnet list package --outdated
   dotnet add package <PackageName> --version <Version>
   

3. The SDK supports .NET 8.0 and .NET 10. Ensure your project targets one of these frameworks:

   <!-- .NET 8.0 (LTS) -->
   <TargetFramework>net8.0</TargetFramework>
   <!-- OR .NET 10 -->
   <TargetFramework>net10.0</TargetFramework>
   

Import Errors

If you see compile-time import errors:

1. Verify the package is installed:

   dotnet list package
   

2. Restore packages explicitly:

   dotnet restore --force
   

3. Clean and rebuild:

   dotnet clean
   dotnet build
   

Next Steps

• Quick Start - Get started quickly
• Configuration - Configure the SDK
• ASP.NET Core Integration - Use in web applications
• API Reference - Explore the API