A comprehensive .NET 8 library that simplifies Google Sheets API interactions for developers who need powerful sheet integration without the complexity. Build custom Google Sheets solutions or use our specialized packages for common use cases.
π Gig Package β Complete gig work tracking guide.
| Badge Name | Status | Site |
|---|---|---|
| Latest Build Status | GitHub Repo | |
| RaptorSheets.Core NuGet | RaptorSheets.Core | |
| RaptorSheets.Gig NuGet | RaptorSheets.Gig | |
| Test Coverage | SonarCloud | |
| Code Quality | SonarCloud | |
| License | - |
# Core library for custom implementations
dotnet add package RaptorSheets.Core
# Or choose a specialized package
dotnet add package RaptorSheets.Gig # For gig work trackingusing RaptorSheets.Core.Services;
using RaptorSheets.Core.Models.Google;
// Set up authentication
var credentials = new Dictionary<string, string>
{
["type"] = "service_account",
["client_email"] = "service@project.iam.gserviceaccount.com",
["private_key"] = "-----BEGIN PRIVATE KEY-----\n...",
// ... other credentials
};
var service = new GoogleSheetService(credentials, spreadsheetId);
// Read data from existing sheet
var sheetData = await service.GetSheetData("MySheet");
Console.WriteLine($"Found {sheetData.Values.Count} rows");using RaptorSheets.Core.Attributes;
using RaptorSheets.Core.Enums;
using RaptorSheets.Core.Repositories;
// Define entities with automatic type conversion
public class ContactEntity
{
public int RowId { get; set; }
// Basic string field with header mapping
[Column(SheetsConfig.HeaderNames.Name, FieldType.String)]
public string Name { get; set; } = "";
// Automatic currency formatting with default "$#,##0.00" pattern
[Column(SheetsConfig.HeaderNames.Salary, FieldType.Currency)]
public decimal? Salary { get; set; }
// Custom format when different from default
[Column(SheetsConfig.HeaderNames.Score, FieldType.Percentage, "0.0%")]
public decimal? Score { get; set; }
// Override JSON name when needed
[Column(SheetsConfig.HeaderNames.EmailAddress, FieldType.Email)]
[JsonPropertyName("email")]
public string EmailAddress { get; set; } = "";
}
// Repository with automatic CRUD operations
public class ContactRepository : BaseEntityRepository<ContactEntity>
{
public ContactRepository(IGoogleSheetService sheetService)
: base(sheetService, "Contacts", hasHeaderRow: true) { }
// Custom business logic methods
public async Task<List<ContactEntity>> GetHighScorersAsync()
{
var allContacts = await GetAllAsync(); // Automatic type conversion
return allContacts.Where(c => c.Score > 0.8m).ToList();
}
}
// Usage
var repository = new ContactRepository(service);
// Automatic type conversion: "$75,000.00" β decimal 75000
var contacts = await repository.GetAllAsync();
// Add new contact with automatic conversion
var newContact = new ContactEntity
{
Name = "John Doe",
Salary = 75000m, // Automatically formatted as "$75,000.00"
Score = 0.95m, // Automatically formatted as "95.0%"
EmailAddress = "john@example.com"
};
await repository.AddAsync(newContact);// Create custom sheet with formatting
var sheetModel = new SheetModel
{
Name = "CustomSheet",
TabColor = ColorEnum.BLUE,
Headers = new List<SheetCellModel>
{
new() { Name = "ID", Format = FormatEnum.NUMBER },
new() { Name = "Name", Format = FormatEnum.TEXT },
new() { Name = "Amount", Format = FormatEnum.CURRENCY }
}
};
// Generate and execute requests
var requests = sheetModel.GenerateRequests();
await service.ExecuteBatchUpdate(requests);- ColumnAttribute: Single attribute for headers, types, and formatting
- Automatic Type Conversion: Currency, dates, percentages, phone numbers, emails
- Default Format Patterns: Specify only when different from sensible defaults
- Header-Driven Configuration: Use header names as primary source of truth
- Repository Pattern: Automatic CRUD operations with type conversion
- π Header Management: Extension methods for column and index assignments with automatic processing
- π¨ Column Formatting: Apply data formatting, configure drop-downs, and set cell protection
- π― Sheet Styling: Alternating row colors, full sheet protection, and custom tab colors
- β‘ Batch Operations: Efficient bulk operations for large datasets with automatic batching
- π Type Safety: Strongly typed entities and enums for all operations
- β Auto Validation: Automatic header validation with detailed error reporting
- π οΈ Error Handling: Comprehensive message system for operation feedback
- π§ͺ Well Tested: Extensive unit and integration test coverage
Your Custom Application
β
TypedField System
βββ ColumnAttribute (Configuration)
βββ BaseEntityRepository<T> (CRUD Operations)
βββ TypedEntityMapper<T> (Conversion)
βββ Schema Validation (Type Safety)
β
RaptorSheets.Core
βββ GoogleSheetService (High-level operations)
βββ SheetServiceWrapper (API abstraction)
βββ Models & Entities (Type safety)
βββ Extensions & Helpers (Utilities)
β
Google Sheets API v4
// Single attribute, automated mapping
[Column(SheetsConfig.HeaderNames.Pay, FieldType.Currency, "\"$\"#,##0.00")]
public decimal? Pay { get; set; }
// Automated conversion in mappers
entity.Pay = MapperHelper.MapField<decimal?>("Pay", row, headers);| Field Type | Auto-Converts | Example Input β Output |
|---|---|---|
Currency |
Dollar amounts | "$1,234.56" β decimal 1234.56 |
PhoneNumber |
Phone formats | "(555) 123-4567" β long 5551234567 |
DateTime |
Date/time values | Google serial β DateTime |
Percentage |
Percentage values | 0.85 β "85.00%" |
Email |
Email addresses | Validation + text format |
Number |
Numeric values | "1,234.56" β decimal 1234.56 |
Integer |
Whole numbers | "1,234" β int 1234 |
Boolean |
True/false | "TRUE" β bool true |
Built on RaptorSheets.Core, these packages provide domain-specific functionality:
| Package | Version | Purpose | Documentation |
|---|---|---|---|
| RaptorSheets.Gig | Complete gig work tracking with automated analytics | π Gig Guide |
Looking for gig work tracking? Check out RaptorSheets.Gig - a complete solution for freelancers and gig workers with pre-built sheets for trips, shifts, earnings, and comprehensive analytics.
- Custom Business Solutions: Build domain-specific Google Sheets integrations for any industry
- Data Pipeline Integration: Automate data sync between your applications and collaborative spreadsheets
- Advanced Report Generation: Create complex reports with formulas, cross-sheet references, and automated calculations
- Workflow Automation: Streamline business processes that rely on Google Sheets data
- Foundation for Specialized Packages: Use as a base to create domain-specific managers (like RaptorSheets.Gig)
RaptorSheets supports multiple authentication methods:
var credentials = new Dictionary<string, string>
{
["type"] = "service_account",
["private_key_id"] = "your-key-id",
["private_key"] = "your-private-key",
["client_email"] = "service@project.iam.gserviceaccount.com",
["client_id"] = "your-client-id"
};var manager = new GoogleSheetManager(accessToken, spreadsheetId);RaptorSheets.Core with TypedField system is designed to be the foundation for domain-specific packages:
// 1. Define your domain entities with ColumnAttribute
public class ProductEntity
{
public int RowId { get; set; }
[Column(SheetsConfig.HeaderNames.ProductName, FieldType.String)]
public string Name { get; set; } = "";
[Column(SheetsConfig.HeaderNames.Price, FieldType.Currency)]
public decimal Price { get; set; }
[Column(SheetsConfig.HeaderNames.LaunchDate, FieldType.DateTime, "M/d/yyyy")]
public DateTime? LaunchDate { get; set; }
}
// 2. Create repository with automatic CRUD
public class ProductRepository : BaseEntityRepository<ProductEntity>
{
public ProductRepository(IGoogleSheetService service)
: base(service, "Products", hasHeaderRow: true) { }
public async Task<List<ProductEntity>> GetExpensiveProductsAsync()
{
var products = await GetAllAsync(); // Automatic conversion
return products.Where(p => p.Price > 100m).ToList();
}
}
// 3. Domain-specific manager
public class ProductManager
{
private readonly ProductRepository _repository;
public ProductManager(Dictionary<string, string> credentials, string spreadsheetId)
{
var service = new GoogleSheetService(credentials, spreadsheetId);
_repository = new ProductRepository(service);
}
public async Task<List<ProductEntity>> GetProductCatalogAsync()
{
return await _repository.GetAllAsync(); // Full type conversion automatically
}
}See RaptorSheets.Gig as a complete example of a specialized package built on the TypedField system.
- .NET 8.0 SDK or later
- Google Cloud Project with Sheets API enabled
- Service Account credentials (recommended) or OAuth2 setup
git clone https://github.com/khanjal/RaptorSheets.git
cd RaptorSheets
dotnet restore
dotnet build
dotnet test# Run all tests
dotnet test
# Run Core library tests specifically
dotnet test RaptorSheets.Core.Tests/
# Run with coverage
dotnet test --collect:"XPlat Code Coverage"- Read/Write requests: 100 requests per 100 seconds per user
- Daily requests: 50,000 requests per day
- π¦ Automatic request batching
- β‘ Efficient data retrieval strategies
- π§ Smart caching mechanisms
- π Rate limit handling with retries
- π TypedField Performance: Cached reflection, efficient type conversion
We welcome contributions to RaptorSheets.Core and the broader ecosystem!
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Focus on Core library enhancements or create new specialized packages
- Write comprehensive tests
- Update relevant documentation
- Submit a Pull Request
- TypedField System: Field types, conversion improvements, validation enhancements
- Core Library: Enhance base functionality, performance, or new Google Sheets features
- New Packages: Create domain-specific packages (Stock, Real Estate, etc.)
- Documentation: Improve guides, examples, and API documentation
- Testing: Add test coverage or performance benchmarks
This project is licensed under the MIT License - see the LICENSE file for details.
- π Report Issues
- π¬ Discussions
- π Google Sheets API Reference
- π Project Homepage
Made with β€οΈ by Iron Raptor Digital