Nextcloud .NET Integration Library

A comprehensive .NET wrapper for Nextcloud integration using WebDAV and OCS APIs. This library provides complete access to Nextcloud functionality including file operations, sharing, calendar/contacts management, user administration, and advanced features.

🚀 Quick Start

# Clone the repository
git clone https://github.com/your-repo/nextcloud-dotnet-integration.git
cd nextcloud-dotnet-integration

# Build the project
dotnet build

# Run tests
dotnet test

📋 Prerequisites

• .NET 8.0 or higher
• Nextcloud instance (tested with Nextcloud 25+)
• Valid Nextcloud user account with appropriate permissions

🛠️ Installation

<PackageReference Include="NextcloudIntegration" Version="1.0.0" />

Or add the source files directly to your project.

🎯 Basic Usage

Initialize the Client

using NextcloudIntegration;

// Main client for file operations, sharing, notifications, and user management
var client = new NextcloudClient("https://cloud.silverlabs.uk", "username", "password");

// Specialized clients
var calDavClient = new NextcloudCalDavClient("https://cloud.silverlabs.uk", "username", "password");
var groupManager = new NextcloudGroupManager(client);

File Operations

// Upload a file
await client.UploadFileAsync("C:\\Documents\\report.pdf", "Reports/annual-report.pdf");

// Upload to another user's directory (requires admin privileges)
await client.UploadFileAsync("C:\\shared.txt", "shared-docs/file.txt", "otheruser");

// Download a file
byte[] fileData = await client.DownloadFileAsync("Reports/annual-report.pdf");
File.WriteAllBytes("C:\\Downloads\\report.pdf", fileData);

// Create folder structure
await client.CreateFolderAsync("Projects/ProjectAlpha/Documents");

// List folder contents with metadata
var files = await client.ListFolderContentsAsync("Reports");
foreach (var file in files)
{
    Console.WriteLine($"{file.Name} - {file.Size} bytes - {file.LastModified}");
}

// Delete file or folder
await client.DeleteFileAsync("old-document.pdf");

Advanced File Operations

// File versioning
var versions = await client.GetFileVersionsAsync("Documents/evolving-doc.docx");
await client.RestoreFileVersionAsync("Documents/evolving-doc.docx", versions[1].Id);

// Trashbin operations
var trashedFiles = await client.GetTrashedFilesAsync();
await client.RestoreFromTrashAsync(trashedFiles[0].Path);
await client.EmptyTrashAsync(); // Permanently delete all trashed files

// Search files
var searchResults = await client.SearchFilesAsync("*.pdf", SearchType.Filename);
var contentResults = await client.SearchFilesAsync("important", SearchType.Content);

// Favorites
await client.AddToFavoritesAsync("Documents/important.pdf");
var favorites = await client.GetFavoritesAsync();
await client.RemoveFromFavoritesAsync("Documents/old-favorite.txt");

// File comments
string commentId = await client.AddFileCommentAsync("12345", "Please review this document");
var comments = await client.GetFileCommentsAsync("12345");
await client.DeleteFileCommentAsync("12345", commentId);

Sharing & Collaboration

// Basic file sharing
string shareId = await client.ShareFileAsync("Documents/report.pdf", "colleague", ShareType.User, SharePermissions.Read);

// Advanced sharing with password and expiration
var shareOptions = new NextcloudShareOptions
{
    Path = "Confidential/sensitive-data.xlsx",
    ShareWith = "manager@company.com",
    ShareType = ShareType.Email,
    Permissions = SharePermissions.Read | SharePermissions.Update,
    Password = "SecurePass123!",
    ExpirationDate = DateTime.Now.AddDays(30),
    Note = "Please review by month end"
};
string advancedShareId = await client.CreateShareAsync(shareOptions);

// Public link sharing
var publicShare = new NextcloudShareOptions
{
    Path = "Public/brochure.pdf",
    ShareType = ShareType.PublicLink,
    Permissions = SharePermissions.Read,
    Password = "PublicAccess2024"
};
string publicShareId = await client.CreateShareAsync(publicShare);
var shareInfo = await client.GetShareAsync(publicShareId);
Console.WriteLine($"Public URL: {shareInfo.Url}");

// Manage existing shares
var allShares = await client.GetSharesAsync("Documents/report.pdf");
await client.UpdateShareAsync(shareId, new NextcloudShareOptions { Password = "NewPassword" });
await client.DeleteShareAsync(shareId);

Notifications

// Send notification to user
await client.SendNotificationAsync("colleague", "New Document", "A new quarterly report is available in the shared folder");

// Get notifications for authenticated user
var notifications = await client.GetNotificationsAsync();
foreach (var notification in notifications)
{
    Console.WriteLine($"{notification.Subject}: {notification.Message}");
}

// Delete specific notification
await client.DeleteNotificationAsync(notifications[0].Id);

Calendar Integration (CalDAV)

// Get all calendars
var calendars = await calDavClient.GetCalendarsAsync();

// Create a new calendar
await calDavClient.CreateCalendarAsync("project-timeline", "Project Timeline", "Important project milestones");

// Create calendar event
var newEvent = new NextcloudCalendarEvent
{
    Summary = "Project Kickoff Meeting",
    Description = "Initial project planning session",
    StartTime = DateTime.Now.AddDays(7).Date.AddHours(9),
    EndTime = DateTime.Now.AddDays(7).Date.AddHours(10.5),
    Location = "Conference Room A"
};
await calDavClient.CreateEventAsync("project-timeline", newEvent);

// Get events in date range
var events = await calDavClient.GetEventsAsync("project-timeline", DateTime.Now, DateTime.Now.AddMonths(1));

Contacts Integration (CardDAV)

// Get address books
var addressBooks = await calDavClient.GetAddressBooksAsync();

// Create new contact
var newContact = new NextcloudContact
{
    FullName = "Jane Smith",
    Email = "jane.smith@company.com",
    PhoneNumber = "+1-555-0123",
    Organization = "Tech Solutions Inc."
};
await calDavClient.CreateContactAsync("contacts", newContact);

// Get all contacts
var contacts = await calDavClient.GetContactsAsync("contacts");

User & Group Management

// User operations
var user = await client.GetUserAsync("username");
var allUsers = await client.GetUsersAsync();

// Group operations (requires admin privileges)
await groupManager.CreateGroupAsync("development-team");
await groupManager.AddUserToGroupAsync("development-team", "developer1");
var groupMembers = await groupManager.GetGroupMembersAsync("development-team");

// User administration
await groupManager.CreateUserAsync("newuser", "password123", "New User", "newuser@company.com");
await groupManager.EnableUserAsync("newuser");
await groupManager.UpdateUserAsync("newuser", "displayname", "Updated Display Name");

Server Capabilities

var capabilities = await client.GetCapabilitiesAsync();
Console.WriteLine($"WebDAV root: {capabilities.Core.WebdavRoot}");
Console.WriteLine($"Big file chunking: {capabilities.Files.BigFileChunking}");
Console.WriteLine($"Notifications available: {capabilities.Notifications}");

🏗️ Architecture

The library is organized into specialized components:

• NextcloudClient: Main client for file operations, sharing, notifications, and user management
• NextcloudCalDavClient: CalDAV operations for calendar and contact management
• NextcloudGroupManager: User and group administration operations
• NextcloudExtensions: Extension methods for additional functionality

🧪 Testing

The library includes comprehensive unit tests with mocked HTTP responses:

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test class
dotnet test --filter "NextcloudClientTests"

📊 Features Overview

🔧 Configuration

Required Nextcloud Apps

Ensure these apps are enabled on your Nextcloud instance:

• Files (core) - File operations
• Files Sharing - Sharing functionality
• Notifications - Admin notifications
• Calendar - CalDAV support
• Contacts - CardDAV support
• Comments - File comments
• Activity - Activity tracking

Authentication

The library supports:

• Basic authentication (username/password)
• App passwords (recommended for production)
• OIDC tokens (via Authorization header)

// Using app password (recommended)
var client = new NextcloudClient("https://cloud.silverlabs.uk", "username", "app-password-token");

// Using OIDC token
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "oidc-token");
// Pass custom HttpClient to client constructor

🚨 Error Handling

All methods throw NextcloudException for Nextcloud-specific errors:

try
{
    await client.UploadFileAsync("file.pdf", "Documents/file.pdf");
}
catch (NextcloudException ex)
{
    Console.WriteLine($"Nextcloud error: {ex.Message}");
    // Handle specific Nextcloud errors (permissions, quota, etc.)
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
    // Handle network connectivity issues
}

📋 Requirements

• .NET: 8.0 or higher
• Nextcloud: 25.0 or higher (tested with latest versions)
• Permissions: Appropriate user permissions for intended operations
• Network: HTTPS connection to Nextcloud instance

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Ensure all tests pass (dotnet test)
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Nextcloud for the excellent cloud platform
• WebDAV specification for file operations standard
• CalDAV/CardDAV specifications for calendar/contacts standards

📞 Support

• Documentation: See /Examples folder for comprehensive usage examples
• Issues: Report bugs via GitHub Issues
• Discussions: Join community discussions for questions and feature requests

Made with ❤️ for the Nextcloud community