Getting TFVC Repository Structure via Azure DevOps Server API

Recently, I was asked an interesting question by a developer who was struggling with Azure DevOps Server APIs around fetching repository metadata for legacy TFVC structures as part of a GitHub migration from ADO Server. This was a nice little problem to solve because, let’s be honest, we don’t really deal with these legacy TFVC repositories much anymore. Most teams have migrated to Git, and the documentation around TFVC API interactions has become somewhat sparse over the years.

The challenge was straightforward but frustrating: they could retrieve project information just fine, but getting the actual TFVC folder structure within each project? That’s where things got tricky. After doing a bit of digging through the API documentation and testing different approaches, I’m happy to say that yes, it is absolutely possible to enumerate all TFVC repositories and their folder structures programmatically.

This blog post shares the solution I put together - a practical approach to retrieve TFVC repository structure using the Azure DevOps Server REST APIs. If you’re working with legacy TFVC repositories and need to interact with them programmatically, this one’s for you.

The Challenge: Understanding TFVC API Limitations

Unlike Git repositories where each project can contain multiple repos, TFVC follows a different model where each project contains exactly one TFVC repository. This fundamental difference affects how you interact with the API and retrieve repository information.

The main challenge developers face is distinguishing between project metadata and actual TFVC repository structure. When calling the standard Projects API, you receive project information but not the folder structure within the TFVC repository itself.

Common Misconceptions About TFVC APIs

Many developers make the mistake of thinking that the Projects API or the Items API with default parameters will return the TFVC folder structure. Here’s what typically happens:

What doesn’t work:

• Using only the Projects API - returns project metadata, not TFVC structure
• Calling Items API without proper scopePath parameter - returns all items across the organization
• Using the Branches API - doesn’t apply to TFVC repositories the same way as Git

The root cause: The API requires specific parameters to traverse the TFVC hierarchy correctly.

Understanding TFVC Repository Structure

In TFVC, the repository structure follows this pattern:

• Each project has one TFVC repository
• The repository root is always $/ProjectName
• Folders are organized hierarchically under this root
• You need to specify recursion levels to control how deep the API traverses

The Solution: Targeted API Calls with Proper Parameters

The key to retrieving TFVC folder structure lies in using the correct combination of API endpoints and parameters. Here’s the step-by-step approach:

Step 1: Get All Projects

First, retrieve all projects in your Azure DevOps Server instance using the Projects API.

Step 2: Query TFVC Items for Each Project

For each project, call the TFVC Items API with these specific parameters:

• scopePath=$/ProjectName - Sets the starting point to the project’s TFVC root
• recursionLevel=OneLevel - Returns immediate children only (not recursive)
• Filter results to show only folders, excluding the root itself

PowerShell Script Implementation

Here’s a complete PowerShell script that implements this solution. You can find the full script and additional TFVC utilities in my TFS/TFVC Scripts collection:

# Azure DevOps Server configuration
$tfsUrl = "https://mytfs.com"
$PAT = "your-personal-access-token"

# Create authentication headers
$headers = @{
    Authorization = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$PAT"))
}

# Get all projects
$projects = Invoke-RestMethod -Uri "$tfsUrl/DefaultCollection/_apis/projects?api-version=5.0" -Headers $headers

foreach ($project in $projects.value) {
    Write-Host "Project: $($project.name)"
    
    # Construct TFVC path for this project
    $tfvcPath = "`$/$($project.name)"
    $itemsUrl = "$tfsUrl/DefaultCollection/$($project.id)/_apis/tfvc/items?scopePath=$tfvcPath&recursionLevel=OneLevel&api-version=5.0"
    
    try {
        # Get TFVC items for this project
        $items = Invoke-RestMethod -Uri $itemsUrl -Headers $headers
        
        # Filter to get only folders (excluding the root itself)
        $folders = $items.value | Where-Object {
            $_.isFolder -eq $true -and
            $_.path -ne $tfvcPath
        }
        
        foreach ($folder in $folders) {
            Write-Host "  - $($folder.path)"
        }
        
        if ($folders.Count -eq 0) {
            Write-Host "  No top-level folders found"
        }
        
    } catch {
        Write-Host "  No TFVC content or access denied"
    }
}

Script Configuration and Security

Personal Access Token Setup

To use this script, you’ll need to create a Personal Access Token (PAT) with appropriate permissions:

1. Navigate to your Azure DevOps Server user settings
2. Create a new Personal Access Token
3. Grant Code (read) permissions at minimum
4. Copy the token and replace your-personal-access-token in the script

URL Configuration

Replace https://mytfs.com with your actual Azure DevOps Server URL. The format should be:

• On-premises TFS: https://your-tfs-server
• Azure DevOps Server: https://your-server-name

Understanding the API Response

The TFVC Items API returns objects with these key properties:

{
    "path": "$/ProjectName/FolderName",
    "isFolder": true,
    "version": 12345,
    "size": 0
}

Important properties:

• path: The full TFVC path to the item
• isFolder: Boolean indicating if the item is a folder
• version: The changeset number when this item was last modified

Error Handling and Edge Cases

The script includes error handling for common scenarios:

No TFVC Repository: Some projects might not have TFVC repositories initialized. The script catches these cases and displays an appropriate message.

Access Permissions: If your PAT doesn’t have sufficient permissions for a project, the API call will fail gracefully.

Empty Repositories: Projects with TFVC repositories but no folders will display “No top-level folders found.”

Advanced Customizations

Filtering Specific Projects

To target specific projects, you can filter the projects array:

$projects = $projects.value | Where-Object { $_.name -like "*YourFilter*" }

Deeper Recursion

To get more than just top-level folders, change the recursionLevel parameter:

• OneLevel: Immediate children only
• Full: Complete hierarchy (use with caution on large repositories)

Output Formatting

You can modify the output format to suit your needs:

# Export to CSV
$results = @()
foreach ($folder in $folders) {
    $results += [PSCustomObject]@{
        Project = $project.name
        FolderPath = $folder.path
        LastModified = $folder.version
    }
}
$results | Export-Csv -Path "tfvc-folders.csv" -NoTypeInformation

Performance Considerations

For organizations with many projects, consider implementing:

Parallel Processing: Use PowerShell jobs or runspaces to query multiple projects simultaneously.

Pagination: For large result sets, implement pagination using the $skip and $top parameters.

Caching: Store results locally if you need to run the script frequently.

Troubleshooting Common Issues

Authentication Failures

• Verify your PAT is not expired
• Ensure the PAT has sufficient permissions
• Check that your TFS URL is correct and accessible

Empty Results

• Confirm the project actually uses TFVC (not Git)
• Verify you have read permissions on the project
• Check if the TFVC repository has been initialized

API Version Compatibility

The script uses API version 5.0, which is compatible with:

• Team Foundation Server 2019 and later
• Azure DevOps Server 2019 and later

For older TFS versions, you might need to use API version 1.0 or 2.0.

Best Practices for TFVC API Integration

Use Specific API Versions: Always specify the API version to ensure consistent behavior across different server versions.

Implement Proper Error Handling: TFVC repositories can have various states, and not all projects may have TFVC initialized.

Respect Rate Limits: While on-premises servers typically don’t have strict rate limits, implement appropriate delays if querying large numbers of projects.

Secure Credential Management: Store PATs securely and rotate them regularly according to your organization’s security policies.

Integration with CI/CD Pipelines

This script can be integrated into DevOps workflows for:

Repository Auditing: Generate reports of TFVC repository structures across your organization.

Migration Planning: Identify repository structures before migrating from TFVC to Git.

Compliance Reporting: Document your source control structure for regulatory requirements.

Key Takeaways

Working with TFVC repositories via REST API requires understanding the fundamental differences between TFVC and Git repository models. The key insights are:

• TFVC has one repository per project, not multiple like Git
• Use scopePath and recursionLevel parameters to control API traversal
• Always filter results to distinguish between folders and the root item
• Implement proper error handling for projects without TFVC repositories

This solution provides a robust foundation for any TFVC repository management tasks you might need to automate. Whether you’re auditing your source control landscape, planning migrations, or building custom tooling, this approach will help you successfully retrieve TFVC repository structure data.

References

• Azure DevOps REST API - TFVC Items
• Azure DevOps REST API - Projects
• Complete PowerShell script on GitHub Gist
• TFS/TFVC Scripts Collection - Additional utilities and examples
• Main image generated by DALL-E