VeeFriends.LinkShortener is a modern, production-ready .NET 9 library and service for creating, managing, and tracking short links. It features robust analytics, QR code generation, and seamless integration with Azure Table Storage, Cloudinary, and Link Preview APIs.
Get Started
$ dotnet add package VeeFriends.LinkShortenerReadme
VeeFriends.LinkShortener 📎✨
VeeFriends.LinkShortener is a modern, production-ready .NET 9 library and service for creating, managing, and tracking short links. It features robust analytics, QR code generation, and seamless integration with Azure Table Storage, Cloudinary, and Link Preview APIs. Designed for extensibility and testability, it supports dependency injection and is fully covered by automated tests.
Features
- Short Link Creation: Generate branded, expiring, and analytics-enabled short URLs.
- Analytics Tracking: Collects and stores detailed analytics for each link visit, including IP, user agent, geo, and device info.
- QR Code Generation: Automatically generates QR codes for each short link.
- Link Preview Integration: Fetches and stores link preview metadata (title, description, image).
- Cloudinary Support: Stores and serves QR codes and images via Cloudinary.
- Azure Table Storage: Fast, scalable, and cost-effective storage for links and analytics.
- Extensible & Testable: Built for dependency injection and easy extension.
- .NET 9 & C# 13: Uses the latest .NET and C# features.
Installation
Install the VeeFriends.LinkShortener NuGet package in your project:
dotnet add package VeeFriends.LinkShortener
Configuration
Configure the necessary services in your Startup.cs or Program.cs file:
using Microsoft.Extensions.DependencyInjection; using VeeFriends.LinkShortener;
var services = new ServiceCollection();
services.AddLinkShortener(options => {
options.AzureTableConnectionString = "your-azure-table-connection-string";
options.CloudinaryApiSecret = "your-cloudinary-api-secret";
options.CloudinaryApiKey = "your-cloudinary-api-key";
options.CloudinaryCloudName = "your-cloudinary-cloud-name";
options.LinkPreviewApiKey = "your-link-preview-api-key";
options.HostUrl = "https://your-shortener-domain.com";
options.QrCodeMoneyApiKey = "your-qrcode-monkey-api-key";
options.ClarityMsTrackingCode = "your-clarity-ms-tracking-code";
});
LinkShortenerConfig Options
| Property | Description | Default |
|---|---|---|
CloudinaryCloudName | Cloudinary cloud name for image hosting. | "" |
CloudinaryApiKey | Cloudinary API key. | "" |
CloudinaryApiSecret | Cloudinary API secret. | "" |
LinkPreviewApiKey | API key for the Link Preview service. | "" |
HostUrl | The base URL for your shortener service. | "https://vf.social" |
AzureTableConnectionString | Azure Table Storage connection string. | "" |
QrCodeMoneyApiKey | API key for QRCode Monkey (for advanced QR code customization). | "" |
ClarityMsTrackingCode | Microsoft Clarity tracking code (for session analytics). | "" |
Usage
ILinkService Overview
The ILinkService interface provides methods for creating, updating, deleting, tracking, and reporting on short links and their analytics.
Core Methods
- CreateLink: Create a new short link with optional custom slug, expiration, and QR code options.
- UpdateLink: Update an existing link's name, URL, expiration, or QR code options.
- DeleteLink: Soft-delete a link by setting its expiration to now.
- GetAllLinks: Retrieve all short links (up to 1000).
- GetLinkBySlug: Retrieve a link by its slug.
- GetAnalytics / GetAnalyticsBySlug: Retrieve analytics for a link by ID or slug.
- TrackView / TrackViewBySlug: Track a view (click or scan) of a link, with support for both
HttpRequestandHttpRequestMessage. - GenerateRedirectPageFromLinkModel: Generate the HTML redirect page for a link, including analytics and tracking code.
- Reporting: Get activity reports, top performing links, and top locations for all links or a specific link.
Example: Creating and Managing Links
public class MyLinkService
{
private readonly ILinkService _linkService;
public MyLinkService(ILinkService linkService)
{
_linkService = linkService;
}
public async Task CreateAndTrackAsync()
{
// Create a new short link
var link = await _linkService.CreateLink(
"My Campaign",
"https://veefriends.com",
slug: null,
expiresAt: DateTime.UtcNow.AddDays(7),
qrCodeOptions: null,
CancellationToken.None
);
// Retrieve by slug
var retrieved = await _linkService.GetLinkBySlug("your-slug", CancellationToken.None);
// Track a view (analytics)
var request = new HttpRequestMessage(HttpMethod.Get, link.ShortUrl);
await _linkService.TrackViewBySlug("your-slug", request, null, false, CancellationToken.None);
// Get analytics
var analytics = await _linkService.GetAnalyticsBySlug("your-slug", CancellationToken.None);
}
}
Example: Analytics
Analytics are automatically tracked for each link visit, including:
- Request method and URL
- IP address and geo lookup (country, region, city)
- User agent, device type, OS, and browser
- Referrer
Retrieve analytics for a link:
var analytics = await linkService.GetAnalyticsBySlug("your-slug", CancellationToken.None);
foreach (var entry in analytics)
{
Console.WriteLine($"{entry.Timestamp}: {entry.IpAddress} - {entry.UserAgent}");
}
Example: Reporting
Generate reports for dashboarding and analytics:
// Get activity report for all links
var report = await linkService.GetLinkActivityReport( DateTime.UtcNow.AddDays(-30), DateTime.UtcNow, CancellationToken.None );
// Get top performing links
var topLinks = await linkService.GetTopPerformingLinks( DateTime.UtcNow.AddDays(-30), DateTime.UtcNow, CancellationToken.None );
// Get top locations for a link
var topLocations = await linkService.GetTopLocationsForLink( linkId, DateTime.UtcNow.AddDays(-30), DateTime.UtcNow, CancellationToken.None );
License
This project is licensed under the MIT License. See the LICENSE file for more details.