Mecesoft.ShortGuid 1.0.5

Mecesoft.ShortGuid

Guid için 22 karakterlik, yalnızca alfasayısal (Base62) kısa temsil sunan bir sarmalayıcı (ShortGuid) ve .NET/EF Core entegrasyonları.

Özellikler

• 22 karakterlik ShortGuid: 0-9, A-Z, a-z (yalnızca alfasayısal). Özel karakter yok. Base62 kodlama.
• Geriye dönük uyumluluk: 22 karakterlik URL‑güvenli Base64 ("-" ve "_") girdilerini de okuyabilir.
• System.Text.Json için gömülü JsonConverter (atribüt ile).
• Binding senaryoları için TypeConverter.
• EF Core için ValueConverter ve model geneli için kolay uzantı (UseShortGuidConverters).
• net9.0 hedefi, Nullable ve ImplicitUsings etkin.

Kurulum

• Projeyi referans alın veya NuGet paketini oluşturup yayınlayın.
• NuGet package ID: Mecesoft.ShortGuid (paketi yerel olarak dotnet pack ile üretebilirsiniz).

Hızlı Başlangıç

1. ShortGuid oluşturma ve yazdırma

using Mecesoft.ShortGuid;

var sg = ShortGuid.NewGuid();
string s = sg.ToString(); // 22 karakter (Base62)
ShortGuid parsed = ShortGuid.Parse(s); // round‑trip
Guid g = sg;                 // implicit cast ShortGuid -> Guid
ShortGuid sg2 = (ShortGuid)g; // implicit cast Guid -> ShortGuid

2. System.Text.Json ile kullanım (atribüt zaten tanımlı)

using System.Text.Json;
using Mecesoft.ShortGuid;

var sg = ShortGuid.NewGuid();
var json = JsonSerializer.Serialize(new { id = sg });
var obj = JsonSerializer.Deserialize<Wrapper>(json);

public record Wrapper(ShortGuid id);

3. EF Core modeli genelinde dönüştürücü uygulama

using Mecesoft.ShortGuid.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    public DbSet<User> Users => Set<User>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.UseShortGuidConverters(); // ShortGuid <-> Guid converter tüm ShortGuid alanlarına uygulanır
    }
}

public class User
{
    public ShortGuid Id { get; set; }
}

ShortGuid biçimi ve uyumluluk

• Birincil çıktı: Base62 ile kodlanmış 22 karakterlik dize (yalnızca 0-9, A-Z, a-z).
• Giriş kabulü: Parse/TryParse şunları kabul eder:
  • Normal Guid dizesi (ör. 32 hex + tireli standart biçimler),
  • 22 karakterlik Base62 ShortGuid,
  • 22 karakterlik URL‑güvenli Base64 ShortGuid ("+" → "-", "/" → "_", sondaki "==" olmadan). Bu mod geriye dönük uyumluluk içindir.

Test Etme (isteğe bağlı örnek)

1. xUnit test projesi oluşturun (Mecesoft.ShortGuid klasörü ile aynı seviyede): TempTests/TempTests.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <IsPackable>false</IsPackable>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <IsTestProject>true</IsTestProject>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
    <PackageReference Include="xunit" Version="2.7.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.7" />
    <PackageReference Include="coverlet.collector" Version="6.0.2" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="../Mecesoft.ShortGuid/Mecesoft.ShortGuid.csproj" />
  </ItemGroup>
</Project>

2. Basit test ekleyin (ShortGuidTests.cs)

using Mecesoft.ShortGuid;
using System.Text.Json;
using Xunit;

public class ShortGuidTests
{
    [Fact]
    public void NewGuid_ToString_Parse_Roundtrip()
    {
        var sg = ShortGuid.NewGuid();
        var s = sg.ToString();
        Assert.Equal(22, s.Length);
        var parsed = ShortGuid.Parse(s);
        Assert.Equal(sg, parsed);
    }

    [Theory]
    [InlineData("5Qqz8l5wQ0mY1m6dH7e5xQ")] // URL‑safe Base64 örneği; geriye dönük kabul edilir
    public void TryParse_Valid22Char_ReturnsTrue(string input)
    {
        var ok = ShortGuid.TryParse(input, out var sg);
        Assert.True(ok);
        Assert.Equal(input, sg.ToString());
    }

    [Fact]
    public void Json_Serializes_And_Deserializes()
    {
        var sg = ShortGuid.NewGuid();
        var json = JsonSerializer.Serialize(new { id = sg });
        var obj = JsonSerializer.Deserialize<Wrapper>(json);
        Assert.NotNull(obj);
        Assert.Equal(sg, obj!.id);
    }

    private record Wrapper(ShortGuid id);
}

3. Çalıştırın: dotnet test TempTests/TempTests.csproj -c Release

Derleme ve Paketleme

• Gereksinimler: .NET SDK 9.x ve NuGet restore için internet.
• Derle: dotnet build Mecesoft.ShortGuid/Mecesoft.ShortGuid.csproj -c Release
• Paketle: dotnet pack Mecesoft.ShortGuid/Mecesoft.ShortGuid.csproj -c Release
  • Projede <GeneratePackageOnBuild>true</GeneratePackageOnBuild> ayarlı olduğundan dotnet build de .nupkg üretir.

EF Core entegrasyonu (notlar)

• Dönüştürücü: ShortGuidConverter : ValueConverter<ShortGuid, Guid> (veritabanında kolon türü Guid olarak kalır).
• Model genelinde uygulama: modelBuilder.UseShortGuidConverters() çağırın.
• Değer nesneleri kullanıyorsanız EF’in CLR türünü gerçekten ShortGuid olarak gördüğünden emin olun; değilse özelliğe özel converter tanımlayın.

Sorun giderme

• Testler bulunamıyorsa dotnet test komutunu kullanın ve Microsoft.NET.Test.Sdk + xunit.runner.visualstudio paketlerinin eklendiğini doğrulayın.
• JSON için System.Text.Json kullanın (Newtonsoft değil); ShortGuid üzerinde [JsonConverter] zaten tanımlıdır.
• EF Core bağlama hatalarında OnModelCreating içinde UseShortGuidConverters() çağrıldığını teyit edin.

Lisans

• MIT License (bkz. LICENSE).