Bestanden downloaden uit Vault met C#

Bestanden downloaden vanuit Vault is de basis van elke automatiseringsworkflow waarbij je de bestandsinhoud nodig hebt: PDF's genereren, parameters uitlezen, assemblies opbouwen. In dit artikel leer je hoe je bestanden efficiënt downloadt via de Vault .NET API — enkelvoudig, in bulk en met volledige foutafhandeling.

Twee methoden voor downloaden

De Vault API biedt twee routes: via FileManager.AcquireFiles (aanbevolen, ondersteunt check-out én read-only download) en via de lager-niveau DocumentService. We gebruiken AcquireFiles — dat is de officiële, stabielere route.

Een bestand downloaden zonder check-out

using Autodesk.Connectivity.WebServices;
using Autodesk.Connectivity.WebServicesTools;
using VDF = Autodesk.DataManagement.Client.Framework;

public string DownloadBestand(
    VDF.Vault.Currency.Connections.Connection conn,
    File vaultBestand,
    string lokaalMap)
{
    Directory.CreateDirectory(lokaalMap);

    // AcquireFiles met Download-optie (geen check-out)
    var settings = new AcquireFilesSettings(conn)
    {
        DefaultAcquisitionOption = FileAcquisitionOptions.Download,
        LocalPath                = new FilePathAbsolute(lokaalMap)
    };
    settings.AddFileToAcquire(vaultBestand, FileAcquisitionOptions.Download);

    var resultaat = conn.FileManager.AcquireFiles(settings);

    if (resultaat.FileResults == null || !resultaat.FileResults.Any())
        throw new Exception($"Download mislukt voor {vaultBestand.Name}.");

    var r = resultaat.FileResults.First();
    if (r.Status != FileAcquisitionStatus.Success)
        throw new Exception($"Download mislukt: {r.Exception?.Message}");

    Console.WriteLine($"✓ Gedownload: {r.LocalPath.FullPath}");
    return r.LocalPath.FullPath;
}

De meest recente versie van een bestand downloaden

public string DownloadLaatsteVersie(
    VDF.Vault.Currency.Connections.Connection conn,
    string vaultBestandsPad)
{
    var docSvc = conn.WebServiceManager.DocumentService;

    // Pad splitsen in map en bestandsnaam
    string map  = Path.GetDirectoryName(vaultBestandsPad)?.Replace('\', '/') ?? "/$";
    string naam = Path.GetFileName(vaultBestandsPad);

    var folder   = docSvc.GetFolderByPath(map);
    var bestanden = docSvc.GetLatestFilesByFolderId(folder.Id, false);
    var bestand  = bestanden?.FirstOrDefault(f => f.Name == naam)
        ?? throw new Exception($"Bestand niet gevonden: {vaultBestandsPad}");

    string lokaalMap = Path.Combine(
        Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
        "VaultDownloads");

    return DownloadBestand(conn, bestand, lokaalMap);
}

Meerdere bestanden tegelijk downloaden (batch)

public Dictionary BatchDownload(
    VDF.Vault.Currency.Connections.Connection conn,
    File[] bestanden,
    string lokaalMap)
{
    Directory.CreateDirectory(lokaalMap);

    var settings = new AcquireFilesSettings(conn)
    {
        DefaultAcquisitionOption = FileAcquisitionOptions.Download,
        LocalPath                = new FilePathAbsolute(lokaalMap)
    };

    foreach (var b in bestanden)
        settings.AddFileToAcquire(b, FileAcquisitionOptions.Download);

    var resultaat = conn.FileManager.AcquireFiles(settings);

    var paden = new Dictionary(); // bestandId → lokaal pad

    foreach (var r in resultaat.FileResults)
    {
        if (r.Status == FileAcquisitionStatus.Success)
        {
            paden[r.File.Id] = r.LocalPath.FullPath;
            Console.WriteLine($"✓ {r.File.Name} → {r.LocalPath.FullPath}");
        }
        else
        {
            Console.WriteLine($"✗ {r.File.Name}: {r.Exception?.Message}");
        }
    }

    return paden;
}

Een volledige map downloaden (recursief)

public void DownloadMap(
    VDF.Vault.Currency.Connections.Connection conn,
    string vaultMapPad,
    string lokaalMap)
{
    var docSvc = conn.WebServiceManager.DocumentService;
    DownloadMapRecursief(conn, docSvc, vaultMapPad, lokaalMap);
}

private void DownloadMapRecursief(
    VDF.Vault.Currency.Connections.Connection conn,
    DocumentService docSvc,
    string vaultMapPad,
    string lokaalMap)
{
    Directory.CreateDirectory(lokaalMap);

    // Download bestanden in deze map
    var folder   = docSvc.GetFolderByPath(vaultMapPad);
    var bestanden = docSvc.GetLatestFilesByFolderId(folder.Id, false);

    if (bestanden?.Length > 0)
        BatchDownload(conn, bestanden, lokaalMap);

    // Verwerk submappen recursief
    var submappen = docSvc.GetFoldersByParentId(folder.Id, false);
    if (submappen == null) return;

    foreach (var sub in submappen)
    {
        string lokaalSub = Path.Combine(lokaalMap, sub.Name);
        string vaultSub  = $"{vaultMapPad}/{sub.Name}";
        DownloadMapRecursief(conn, docSvc, vaultSub, lokaalSub);
    }
}

Versiegeschiedenis ophalen en specifieke versie downloaden

public void ToonVersiegeschiedenis(DocumentService docSvc, File bestand)
{
    // Alle versies van een bestand ophalen via MasterId
    var versies = docSvc.GetFilesByMasterId(bestand.MasterId);

    Console.WriteLine($"Versiegeschiedenis van {bestand.Name}:");
    foreach (var v in versies.OrderBy(v => v.VerNum))
    {
        Console.WriteLine($"  v{v.VerNum,-4} Ingecheckt op: {v.CkInDate:dd-MM-yyyy HH:mm}  Door: {v.FileClass}");
    }
}

// Specifieke versie downloaden:
public string DownloadSpecifiekeVersie(
    VDF.Vault.Currency.Connections.Connection conn,
    File vaultBestand,
    int versienummer,
    string lokaalMap)
{
    // Haal de specifieke versie op via GetFilesByMasterId
    var versies = conn.WebServiceManager.DocumentService
        .GetFilesByMasterId(vaultBestand.MasterId);

    var versie = versies.FirstOrDefault(v => v.VerNum == versienummer)
        ?? throw new Exception($"Versie {versienummer} niet gevonden.");

    return DownloadBestand(conn, versie, lokaalMap);
}

Download combineren met verdere verwerking

Een typisch gebruiksscenario: download bestanden, verwerk ze (PDF genereren, iProperties updaten), en check ze terug in:

public void VolledigeWorkflow(VDF.Vault.Currency.Connections.Connection conn,
    string[] vaultPaden, string werkmap, string commentaar)
{
    var docSvc = conn.WebServiceManager.DocumentService;
    var log    = new List();

    foreach (var pad in vaultPaden)
    {
        File bestand = null;
        try
        {
            // 1. Bestand zoeken
            string mapPad   = Path.GetDirectoryName(pad)?.Replace('\', '/') ?? "/$";
            string bestandNm = Path.GetFileName(pad);
            var folder      = docSvc.GetFolderByPath(mapPad);
            bestand         = docSvc.GetLatestFilesByFolderId(folder.Id, false)
                ?.FirstOrDefault(f => f.Name == bestandNm);

            if (bestand == null) { log.Add($"NIET GEVONDEN: {pad}"); continue; }

            // 2. Download (read-only, geen check-out)
            string lokaalPad = DownloadBestand(conn, bestand, werkmap);

            // 3. Verwerking (hier jouw logica)
            // bijv. InvApp.Documents.Open(lokaalPad) en PDF exporteren

            log.Add($"OK: {bestandNm}");
        }
        catch (Exception ex)
        {
            log.Add($"FOUT: {Path.GetFileName(pad)}: {ex.Message}");
        }
    }

    // Log wegschrijven
    File.WriteAllLines(Path.Combine(werkmap, "workflow_log.txt"), log,
        System.Text.Encoding.UTF8);
    Console.WriteLine($"Workflow klaar. {log.Count(l => l.StartsWith("OK"))} succesvol.");
}

Veelgemaakte fouten

Lokaal bestand bestaat al — standaard overschrijft AcquireFiles bestaande lokale bestanden. Wil je dat niet, controleer dan eerst of het bestand al aanwezig is en of het de juiste versie heeft.

Netwerkproblemen bij grote batches — bij het downloaden van honderden grote bestanden kan een time-out optreden. Splits grote batches op in kleinere delen (bv. 50 bestanden per batch).

Pad-separators — Vault-mappaden gebruiken forward slashes (/). Windows-bestandspaden gebruiken backslashes. Converteer altijd: vaultPad.Replace('\', '/').

GetLatestFilesByFolderId geeft null — een lege map geeft null terug, geen lege array. Controleer altijd op null.

Samenvatting

Bestanden downloaden uit Vault via C# is eenvoudig met AcquireFilesSettings en FileManager.AcquireFiles. Gebruik de Download-optie voor read-only toegang en combineer batch-downloads met foutafhandeling per item. Dit is de basis voor alle geautomatiseerde workflows waarbij bestandsinhoud nodig is.

Downloading files from Vault is the foundation of any automation workflow that needs file content: generating PDFs, reading parameters, building assemblies. This article shows how to download files efficiently via the Vault .NET API — individually, in batch and with full error handling.

Two Methods for Downloading

The Vault API offers two routes: via FileManager.AcquireFiles (recommended, supports both check-out and read-only download) and via the lower-level DocumentService. We use AcquireFiles — the official, more stable route.

Downloading a File Without Check-out

public string DownloadFile(Connection conn, File vaultFile, string localFolder)
{
    Directory.CreateDirectory(localFolder);
    var settings = new AcquireFilesSettings(conn)
    {
        DefaultAcquisitionOption = FileAcquisitionOptions.Download,
        LocalPath                = new FilePathAbsolute(localFolder)
    };
    settings.AddFileToAcquire(vaultFile, FileAcquisitionOptions.Download);
    var result = conn.FileManager.AcquireFiles(settings);
    var r      = result.FileResults.First();
    if (r.Status != FileAcquisitionStatus.Success)
        throw new Exception($"Download failed: {r.Exception?.Message}");
    return r.LocalPath.FullPath;
}

Downloading the Latest Version

var folder    = docSvc.GetFolderByPath(vaultFolderPath);
var files     = docSvc.GetLatestFilesByFolderId(folder.Id, false);
var file      = files?.FirstOrDefault(f => f.Name == fileName)
    ?? throw new Exception("File not found.");
string local  = DownloadFile(conn, file, localWorkDir);

Batch Download

var settings = new AcquireFilesSettings(conn)
{
    DefaultAcquisitionOption = FileAcquisitionOptions.Download,
    LocalPath = new FilePathAbsolute(localFolder)
};
foreach (var f in files) settings.AddFileToAcquire(f, FileAcquisitionOptions.Download);
var result = conn.FileManager.AcquireFiles(settings);

foreach (var r in result.FileResults)
    Console.WriteLine(r.Status == FileAcquisitionStatus.Success
        ? $"✓ {r.File.Name} → {r.LocalPath.FullPath}"
        : $"✗ {r.File.Name}: {r.Exception?.Message}");

Recursive Folder Download

private void DownloadFolderRecursive(Connection conn, DocumentService docSvc,
    string vaultPath, string localPath)
{
    Directory.CreateDirectory(localPath);
    var folder = docSvc.GetFolderByPath(vaultPath);
    var files  = docSvc.GetLatestFilesByFolderId(folder.Id, false);
    if (files?.Length > 0) BatchDownload(conn, files, localPath);

    var subFolders = docSvc.GetFoldersByParentId(folder.Id, false);
    if (subFolders == null) return;
    foreach (var sub in subFolders)
        DownloadFolderRecursive(conn, docSvc, $"{vaultPath}/{sub.Name}",
            Path.Combine(localPath, sub.Name));
}

Version History and Specific Version Download

// All versions of a file
var versions = docSvc.GetFilesByMasterId(file.MasterId);
foreach (var v in versions.OrderBy(v => v.VerNum))
    Console.WriteLine($"v{v.VerNum}: checked in {v.CkInDate:dd-MM-yyyy}");

// Download specific version
var specificVersion = versions.First(v => v.VerNum == targetVersion);
string localPath = DownloadFile(conn, specificVersion, localWorkDir);

Common Pitfalls

Existing local file — by default AcquireFiles overwrites existing local files. If you don't want that, check first whether the file already exists with the correct version.

Network timeouts on large batches — split large batches into smaller chunks (e.g. 50 files per batch) to avoid timeouts.

Path separators — Vault folder paths use forward slashes (/). Always convert: vaultPath.Replace('\', '/').

GetLatestFilesByFolderId returns null — an empty folder returns null, not an empty array. Always null-check.

Summary

Downloading files from Vault in C# is straightforward with AcquireFilesSettings and FileManager.AcquireFiles. Use the Download option for read-only access and combine batch downloads with per-item error handling. This is the foundation for all automated workflows that need file content.