C# voor Vault: Bestandsoperaties automatiseren met de Vault API

Waarom Vault automatiseren met C#?

Autodesk Vault is een databeheersysteem — elk bestand, elke revisie en elke eigenschap staat in een gestructureerde database. De Vault SDK stelt deze database beschikbaar via webserviceproxy's die je vanuit C# kunt aanroepen. Dat betekent dat je vrijwel alles kunt automatiseren: bulksgewijze eigenschapsupdates, nachtelijke exports, vrijgaveworkflows, systeemoverschrijdende synchronisatie.

Dit bericht behandelt de grondbeginselen: de SDK instellen, authenticeren, bestanden zoeken en een in-/uitcheck-cyclus uitvoeren.

Vereisten

Visual Studio 2019 of 2022
Autodesk Vault Professional 2020 of later (client- én servertoegang)
Autodesk Vault SDK — te downloaden van het Autodesk Developer Network of te installeren via het Vault-clientinstallatieprogramma (selecteer "SDK" bij optionele onderdelen)
Basiskennis C#

Stap 1 — Project aanmaken en referenties toevoegen

Maak een Console App (.NET Framework 4.8) aan in Visual Studio. Voeg vervolgens referenties toe aan de Vault SDK-assemblies. Die staan standaard in:

C:\Program Files\Autodesk\Vault 2024 SDK\bin\

Voeg deze DLL's toe:

Autodesk.Connectivity.WebServices.dll
Autodesk.Connectivity.WebServicesTools.dll
Autodesk.DataManagement.Client.Framework.dll
Autodesk.DataManagement.Client.Framework.Vault.dll

Stel Copy Local = True in voor al deze DLL's — anders dan AutoCAD worden Vault SDK-assemblies niet vooraf geladen en moeten ze worden meegeleverd met je applicatie.

Stap 2 — Verbinding maken en authenticeren

Het startpunt van de Vault API is de WebServiceManager, verkregen via UserPasswordCredentials:

using System;
using Autodesk.Connectivity.WebServices;
using Autodesk.Connectivity.WebServicesTools;

namespace VaultAutomatisering
{
    class Program
    {
        static void Main(string[] args)
        {
            string server   = "localhost";     // Vault-servernaam of IP-adres
            string vault    = "Vault";         // Vault-databasenaam (zichtbaar in titelvenster Vault-client)
            string username = "Administrator";
            string password = "";              // standaard leeg voor Administrator

            UserPasswordCredentials credentials = new UserPasswordCredentials(
                server, vault, username, password);

            using (WebServiceManager svcMgr = new WebServiceManager(credentials))
            {
                Console.WriteLine($"Verbonden met vault: {vault} op {server}");
                Console.WriteLine($"Aangemeld als: {svcMgr.SecurityService.SecurityHeader.UserId}");

                // Alle Vault-bewerkingen staan hier — svcMgr is de gateway
                ZoekBestanden(svcMgr);
            }

            Console.WriteLine("Klaar. Druk op een toets om af te sluiten.");
            Console.ReadKey();
        }
    }
}

Stap 3 — Bestanden zoeken

De meest voorkomende eerste bewerking is bestanden zoeken. De zoek-API van Vault werkt met condities — je bouwt een array van SrchCond-objecten:

static void ZoekBestanden(WebServiceManager svcMgr)
{
    // Eigenschapdefinitie "Naam" ophalen om op te zoeken
    PropDef[] allProps = svcMgr.PropertyService.GetPropertyDefinitionsByEntityClassId("FILE");
    PropDef fileNameProp = Array.Find(allProps, p => p.DispName == "Name");

    // Zoekconditie: naam bevat "Bracket"
    SrchCond condition = new SrchCond
    {
        PropDefId = fileNameProp.Id,
        PropTyp   = PropertySearchType.SingleProperty,
        SrchOper  = 1,        // 1 = bevat
        SrchTxt   = "Bracket",
        SrchRule  = SearchRuleType.Must
    };

    // Vault geeft resultaten in pagina's terug (bladwijzers)
    string bookmark = string.Empty;
    SrchStatus status;

    File[] results = svcMgr.DocumentService.FindFilesBySearchConditions(
        new[] { condition },
        sortConditions: null,
        folderIds:      null,   // null = zoek in alle mappen
        recurseFolders: true,
        latestOnly:     true,
        bookmark:       ref bookmark,
        searchStatus:   out status);

    if (results == null || results.Length == 0)
    {
        Console.WriteLine("Geen bestanden gevonden.");
        return;
    }

    Console.WriteLine($"{results.Length} bestand(en) gevonden:");
    foreach (File f in results)
    {
        Console.WriteLine($"  {f.Name}  (ver {f.FileRev.Label})  [{f.CheckedOut}]");
    }
}

Stap 4 — Uitchecken, eigenschap bijwerken en inchecken

De in-/uitcheckfunctie is de kern van elke Vault-workflow. Hier is een volledig voorbeeld:

static void CheckOutEnBijwerken(WebServiceManager svcMgr, long fileId)
{
    // ── 1. Bestand ophalen ───────────────────────────────────────────────
    File vaultFile = svcMgr.DocumentService.GetFileById(fileId);
    Console.WriteLine($"Bezig met: {vaultFile.Name}");

    // ── 2. Uitchecken ────────────────────────────────────────────────────
    string downloadMap = @"C:\VaultWerkmap";
    System.IO.Directory.CreateDirectory(downloadMap);

    FileIteration checkedOut = svcMgr.DocumentServiceExtensions
        .CheckoutFile(vaultFile.Id, CheckoutFileOptions.Master, downloadMap);

    string lokaalBestand = System.IO.Path.Combine(downloadMap, vaultFile.Name);
    Console.WriteLine($"Uitgecheckt naar: {lokaalBestand}");

    // ── 3. Aangepaste eigenschap bijwerken ───────────────────────────────
    PropDef[] defs = svcMgr.PropertyService.GetPropertyDefinitionsByEntityClassId("FILE");
    PropDef descProp = Array.Find(defs, p => p.DispName == "Description");

    PropInst newProp = new PropInst
    {
        EntityId  = vaultFile.Id,
        PropDefId = descProp.Id,
        Val       = "Bijgewerkt door automatisering op " + DateTime.Now.ToString("yyyy-MM-dd")
    };
    svcMgr.PropertyService.UpdateProperties(
        "FILE",
        new[] { vaultFile.Id },
        new[] { newProp });

    Console.WriteLine("Eigenschap bijgewerkt.");

    // ── 4. Inchecken ─────────────────────────────────────────────────────
    ByteArray uploadTick = svcMgr.FilestoreService.AddFile(
        checkedOut.MasterRevId.ToString(),
        "Ingecheckt door automatisering",
        lokaalBestand);

    svcMgr.DocumentService.CheckinUploadedFile(
        vaultFile.Id,
        "Geautomatiseerde eigenschapsupdate",
        keepCheckedOut: false,
        localLastWrite: System.IO.File.GetLastWriteTime(lokaalBestand),
        fileContentsHash: uploadTick,
        bom: null);

    Console.WriteLine($"Ingecheckt: {vaultFile.Name}");
}

Kernconcepten

WebServiceManager is je enige verbindingsobject. Het stelt afzonderlijke serviceclients beschikbaar voor elk onderdeel van de Vault API. Gebruik het altijd binnen een using-blok zodat de verbinding netjes wordt gesloten.

Eigenschapdefinities vs. instanties — een PropDef beschrijft een eigenschap (naam, type en ID). Een PropInst is de feitelijke waarde op een specifiek bestand. Haal definities eenmalig op en cache ze; lees en schrijf instanties per bestand.

Vault-ID's — elk bestand, elke map, elke gebruiker en elke eigenschap heeft een numeriek ID. Zoekresultaten geven je ID's; de meeste vervolgbewerkingen nemen ID's in plaats van namen. Namen kunnen veranderen, ID's nooit.

Bladwijzers — Vault geeft zoekresultaten in pagina's terug. Als je meer dan een paar honderd resultaten verwacht, loop dan totdat searchStatus.IndetermFnd false is en de bladwijzer stopt met veranderen.

Overzicht van nuttige services

DocumentService — bestanden, mappen, in-/uitchecken, levenscyclusstatus
PropertyService — aangepaste eigenschappen, eigenschapdefinities
FilestoreService — bestanden uploaden en downloaden op laag niveau
SecurityService — gebruikers, groepen, machtigingen
ItemService — items (de stuklijst-/engineeringlaag boven bestanden)
RevisionService — revisieschema's en -labels

Wat volgt

Met de verbinding en basisbestandsoperaties werkend behandelen de volgende lessen:

Bulksgewijze eigenschapsupdates — efficiënt door honderden bestanden lopen
Levenscyclustransities — bestanden door review- en vrijgavestatus sturen
Mapstructuurautomatisering — Vault-mappen per project aanmaken en organiseren
Een Vault Explorer-plugin bouwen met een aangepast contextmenu

De volledige C# voor Vault-cursus is beschikbaar voor Standard- en Full Access-abonnees in de E-Learning-sectie.

Why automate Vault with C#?

Autodesk Vault is a data management system — every file, revision, and property lives in a structured database. The Vault SDK exposes this database through a set of web service proxies that you can call from C#. That means you can automate almost anything: bulk property updates, nightly exports, release workflows, cross-system synchronisation.

This post covers the fundamentals: setting up the SDK, authenticating, searching for files, and performing a check-out / check-in cycle.

Prerequisites

Visual Studio 2019 or 2022
Autodesk Vault Professional 2020 or later (client + server access)
Autodesk Vault SDK — download from the Autodesk Developer Network or install via the Vault client installer (select "SDK" in the optional components)
Basic C# knowledge

Step 1 — Create the project and add references

Create a Console App (.NET Framework 4.8) in Visual Studio. Then add references to the Vault SDK assemblies. They are typically found at:

C:\Program Files\Autodesk\Vault 2024 SDK\bin\

Add these DLLs:

Autodesk.Connectivity.WebServices.dll
Autodesk.Connectivity.WebServicesTools.dll
Autodesk.DataManagement.Client.Framework.dll
Autodesk.DataManagement.Client.Framework.Vault.dll

Set Copy Local = True for all of these — unlike AutoCAD, Vault SDK assemblies are not pre-loaded and must travel with your application.

Step 2 — Connect and authenticate

The entry point to the Vault API is the WebServiceManager, obtained through a UserPasswordCredentials login:

using System;
using Autodesk.Connectivity.WebServices;
using Autodesk.Connectivity.WebServicesTools;

namespace VaultAutomation
{
    class Program
    {
        static void Main(string[] args)
        {
            // Connection parameters
            string server   = "localhost";  // Vault server name or IP
            string vault    = "Vault";      // Vault database name (shown in Vault client title bar)
            string username = "Administrator";
            string password = "";           // empty by default for Administrator

            // Create credentials and connect
            UserPasswordCredentials credentials = new UserPasswordCredentials(
                server, vault, username, password);

            using (WebServiceManager svcMgr = new WebServiceManager(credentials))
            {
                Console.WriteLine($"Connected to vault: {vault} on {server}");
                Console.WriteLine($"Logged in as: {svcMgr.SecurityService.SecurityHeader.UserId}");

                // All your Vault operations go here — svcMgr is your gateway
                SearchForFiles(svcMgr);
            }

            Console.WriteLine("Done. Press any key to exit.");
            Console.ReadKey();
        }
    }
}

Step 3 — Search for files

The most common first operation is finding files. Vault's search API is condition-based — you build an array of SrchCond (search condition) objects:

static void SearchForFiles(WebServiceManager svcMgr)
{
    // Find the property definition for "File Name" to search by
    PropDef[] allProps = svcMgr.PropertyService.GetPropertyDefinitionsByEntityClassId("FILE");
    PropDef fileNameProp = Array.Find(allProps, p => p.DispName == "Name");

    // Build a search condition: Name contains "Bracket"
    SrchCond condition = new SrchCond
    {
        PropDefId   = fileNameProp.Id,
        PropTyp     = PropertySearchType.SingleProperty,
        SrchOper    = 1,     // 1 = contains
        SrchTxt     = "Bracket",
        SrchRule    = SearchRuleType.Must
    };

    // Run the search — Vault returns results in pages (bookmarks)
    string bookmark = string.Empty;
    SrchStatus status;

    File[] results = svcMgr.DocumentService.FindFilesBySearchConditions(
        new[] { condition },
        sortConditions: null,
        folderIds:      null,   // null = search all folders
        recurseFolders: true,
        latestOnly:     true,
        bookmark:       ref bookmark,
        searchStatus:   out status);

    if (results == null || results.Length == 0)
    {
        Console.WriteLine("No files found.");
        return;
    }

    Console.WriteLine($"Found {results.Length} file(s):");
    foreach (File f in results)
    {
        Console.WriteLine($"  {f.Name}  (ver {f.FileRev.Label})  [{f.CheckedOut}]");
    }
}

Step 4 — Check out, modify properties, and check in

The check-out / check-in cycle is at the heart of any Vault workflow. Here's a complete example:

static void CheckOutAndUpdateProperty(WebServiceManager svcMgr, long fileId)
{
    // ── 1. Get the file ────────────────────────────────────────────────
    File vaultFile = svcMgr.DocumentService.GetFileById(fileId);
    Console.WriteLine($"Working with: {vaultFile.Name}");

    // ── 2. Check out ───────────────────────────────────────────────────
    // localPath is where the file will be downloaded on this machine
    string downloadFolder = @"C:\VaultWorkingFolder";
    System.IO.Directory.CreateDirectory(downloadFolder);

    FileIteration checkedOut = svcMgr.DocumentServiceExtensions
        .CheckoutFile(vaultFile.Id, CheckoutFileOptions.Master, downloadFolder);

    string localFile = System.IO.Path.Combine(downloadFolder, vaultFile.Name);
    Console.WriteLine($"Checked out to: {localFile}");

    // ── 3. Update a custom property ────────────────────────────────────
    // Find the property definition for "Description"
    PropDef[] defs = svcMgr.PropertyService.GetPropertyDefinitionsByEntityClassId("FILE");
    PropDef descProp = Array.Find(defs, p => p.DispName == "Description");

    // Set the new value
    PropInst newProp = new PropInst
    {
        EntityId    = vaultFile.Id,
        PropDefId   = descProp.Id,
        Val         = "Updated by automation on " + DateTime.Now.ToString("yyyy-MM-dd")
    };
    svcMgr.PropertyService.UpdateProperties(
        "FILE",
        new[] { vaultFile.Id },
        new[] { newProp });

    Console.WriteLine("Property updated.");

    // ── 4. Check in ────────────────────────────────────────────────────
    // The file must exist at localFile for check-in to succeed.
    // Here we just check it back in without actually modifying the file content.
    ByteArray uploadTick = svcMgr.FilestoreService.AddFile(
        checkedOut.MasterRevId.ToString(),
        "Checked in by automation",
        localFile);

    svcMgr.DocumentService.CheckinUploadedFile(
        vaultFile.Id,
        "Automated property update",     // comment visible in Vault history
        keepCheckedOut: false,
        localLastWrite: System.IO.File.GetLastWriteTime(localFile),
        fileContentsHash: uploadTick,
        bom: null);

    Console.WriteLine($"Checked in: {vaultFile.Name}");
}

Key concepts

WebServiceManager is your single connection object. It exposes individual service clients (DocumentService, PropertyService, FilestoreService, etc.) for each area of the Vault API. Always use it inside a using block so the connection is closed cleanly.

Property definitions vs property instances — a PropDef describes a property (its name, type, and ID). A PropInst is the actual value of that property on a specific file. You look up definitions once and cache them; you read and write instances per file.

Vault IDs — every file, folder, user, and property has a numeric ID. The search results give you IDs; most subsequent operations take IDs rather than names. This is intentional — names can change, IDs never do.

Bookmarks — Vault search returns results in pages. If you expect more than a few hundred results, loop until searchStatus.IndetermFnd is false and bookmark stops changing.

Useful services overview

DocumentService — files, folders, check in/out, lifecycle state
PropertyService — custom properties, property definitions
FilestoreService — low-level file upload and download
SecurityService — users, groups, permissions
ItemService — items (the BOM/engineering item layer above files)
RevisionService — revision schemes and labels

What's next

With the connection and basic file operations working, the next lessons cover:

Bulk property updates — looping through hundreds of files efficiently
Lifecycle transitions — moving files through review and release states
Folder structure automation — creating and organising vault folders by project
Building a Vault Explorer plugin with a custom right-click menu

The full C# for Vault course is available to Standard and Full Access subscribers in the E-Learning section.

C# voor Vault: Bestandsoperaties automatiseren met de Vault API

Waarom Vault automatiseren met C#?

Vereisten

Stap 1 — Project aanmaken en referenties toevoegen

Stap 2 — Verbinding maken en authenticeren

Stap 3 — Bestanden zoeken

Stap 4 — Uitchecken, eigenschap bijwerken en inchecken

Kernconcepten

Overzicht van nuttige services

Wat volgt

Why automate Vault with C#?

Prerequisites

Step 1 — Create the project and add references

Step 2 — Connect and authenticate

Step 3 — Search for files

Step 4 — Check out, modify properties, and check in

Key concepts

Useful services overview

What's next

Comments

Leave a comment

C# voor Vault: Bestandsoperaties automatiseren met de Vault API

Waarom Vault automatiseren met C#?

Vereisten

Stap 1 — Project aanmaken en referenties toevoegen

Stap 2 — Verbinding maken en authenticeren

Stap 3 — Bestanden zoeken

Stap 4 — Uitchecken, eigenschap bijwerken en inchecken

Kernconcepten

Overzicht van nuttige services

Wat volgt

Why automate Vault with C#?

Prerequisites

Step 1 — Create the project and add references

Step 2 — Connect and authenticate

Step 3 — Search for files

Step 4 — Check out, modify properties, and check in

Key concepts

Useful services overview

What's next

More articles

Comments

Leave a comment