De clientbibliotheek voor elastische databases gebruiken met Dapper
Van toepassing op:
Azure SQL Database
Dit document is bedoeld voor ontwikkelaars die afhankelijk zijn van Dapper om toepassingen te bouwen, maar ook elastische databasehulpprogramma's willen gebruiken om toepassingen te maken die sharding implementeren om hun gegevenslaag uit te schalen. Dit document illustreert de wijzigingen in Dapper-toepassingen die nodig zijn om te integreren met hulpmiddelen voor elastische databases. Onze focus ligt op het opstellen van het shardbeheer van de elastische database en gegevensafhankelijke routering met Dapper.
Voorbeeldcode: Hulpprogramma's voor elastische databases voor Azure SQL Database - Dapper-integratie.
De integratie van Dapper en DapperExtensions met de clientbibliotheek voor elastische databases voor Azure SQL Database is eenvoudig. Uw toepassingen kunnen gegevensafhankelijke routering gebruiken door het maken en openen van nieuwe Sql Verbinding maken ion-objecten te wijzigen om de aanroep Open Verbinding maken ionForKey uit de clientbibliotheek te gebruiken. Hierdoor worden wijzigingen in uw toepassing beperkt tot alleen waar nieuwe verbindingen worden gemaakt en geopend.
Dapper-overzicht
Dapper is een object-relationele mapper. Het wijst .NET-objecten van uw toepassing toe aan een relationele database (en omgekeerd). In het eerste deel van de voorbeeldcode ziet u hoe u de clientbibliotheek voor elastische databases kunt integreren met Dapper-toepassingen. Het tweede deel van de voorbeeldcode illustreert hoe u integreert wanneer u zowel Dapper als DapperExtensions gebruikt.
De mapper-functionaliteit in Dapper biedt uitbreidingsmethoden voor databaseverbindingen die het indienen van T-SQL-instructies vereenvoudigen voor uitvoering of het uitvoeren van query's op de database. Dapper maakt het bijvoorbeeld eenvoudig om te koppelen tussen uw .NET-objecten en de parameters van SQL-instructies voor Execute-aanroepen , of om de resultaten van uw SQL-query's te gebruiken in .NET-objecten met behulp van Query-aanroepen van Dapper.
Wanneer u DapperExtensions gebruikt, hoeft u de SQL-instructies niet meer op te geven. Met uitbreidingsmethoden zoals GetList of Insert via de databaseverbinding worden de SQL-instructies achter de schermen gemaakt.
Een ander voordeel van Dapper en ook DapperExtensions is dat de toepassing het maken van de databaseverbinding regelt. Dit helpt om te communiceren met de clientbibliotheek voor elastische databases die databaseverbindingen brokers op basis van de toewijzing van shardlets aan databases.
Zie Dapper dot net om de Dapper-assembly's te verkrijgen. Zie DapperExtensions voor de Dapper extensies.
Een kort overzicht van de clientbibliotheek voor elastische databases
Met de clientbibliotheek voor elastische databases definieert u partities van uw toepassingsgegevens, shardlets genoemd, wijst u deze toe aan databases en identificeert u deze door shardingsleutels. U kunt zoveel databases hebben als u nodig hebt en uw shardlets over deze databases verdelen. De toewijzing van sharding-sleutelwaarden aan de databases wordt opgeslagen door een shard-toewijzing die wordt geleverd door de API's van de bibliotheek. Deze mogelijkheid wordt shard-toewijzingsbeheer genoemd. De shard-toewijzing dient ook als broker voor databaseverbindingen voor aanvragen die een sharding-sleutel bevatten. Deze mogelijkheid wordt aangeduid als gegevensafhankelijke routering.
Met shard-toewijzingsbeheer worden gebruikers beschermd tegen inconsistente weergaven in shardlet-gegevens die kunnen optreden wanneer gelijktijdige shardlet-beheerbewerkingen worden uitgevoerd op de databases. Hiervoor wijst de shard de databaseverbindingen toe voor een toepassing die is gebouwd met de bibliotheek. Wanneer shardbeheerbewerkingen van invloed kunnen zijn op de shardlet, kan de shardtoewijzingsfunctionaliteit automatisch een databaseverbinding beëindigen.
In plaats van de traditionele manier te gebruiken om verbindingen te maken voor Dapper, moet u de methode Open Verbinding maken ionForKey gebruiken. Dit zorgt ervoor dat alle validatie plaatsvindt en dat verbindingen correct worden beheerd wanneer gegevens tussen shards worden verplaatst.
Vereisten voor Dapper-integratie
Wanneer u met zowel de elastic database-clientbibliotheek als de Dapper-API's werkt, wilt u de volgende eigenschappen behouden:
- Uitschalen: We willen databases toevoegen aan of verwijderen uit de gegevenslaag van de shard-toepassing, indien nodig voor de capaciteitsvereisten van de toepassing.
- Consistentie: Omdat de toepassing wordt uitgeschaald met behulp van sharding, moet u gegevensafhankelijke routering uitvoeren. Hiervoor willen we de gegevensafhankelijke routeringsmogelijkheden van de bibliotheek gebruiken. U wilt met name de validatie- en consistentiegaranties behouden die worden geboden door verbindingen die worden brokered via shard-toewijzingsbeheer om beschadiging of onjuiste queryresultaten te voorkomen. Dit zorgt ervoor dat verbindingen met een bepaalde shardlet worden geweigerd of gestopt als (bijvoorbeeld) de shardlet momenteel wordt verplaatst naar een andere shard met behulp van Split/Merge-API's.
- Objecttoewijzing: We willen het gemak van de toewijzingen van Dapper behouden om te vertalen tussen klassen in de toepassing en de onderliggende databasestructuren.
In de volgende sectie vindt u richtlijnen voor deze vereisten voor toepassingen op basis van Dapper en DapperExtensions.
Technische begeleiding
Gegevensafhankelijke routering met Dapper
Met Dapper is de toepassing doorgaans verantwoordelijk voor het maken en openen van de verbindingen met de onderliggende database. Op basis van een type T door de toepassing retourneert Dapper queryresultaten als .NET-verzamelingen van het type T. Dapper voert de toewijzing uit van de T-SQL-resultaatrijen naar de objecten van het type T. Op dezelfde manier wijst Dapper .NET-objecten toe aan SQL-waarden of -parameters voor DML-instructies (Data Manipulat Language). Dapper biedt deze functionaliteit via extensiemethoden op de reguliere Sql Verbinding maken ion-object uit de ADO .NET SQL Client-bibliotheken. De SQL-verbinding die wordt geretourneerd door de Elastic Scale-API's voor DDR, zijn ook reguliere Sql Verbinding maken ion-objecten. Hierdoor kunnen we dapper-extensies rechtstreeks gebruiken voor het type dat wordt geretourneerd door de DDR-API van de clientbibliotheek, omdat het ook een eenvoudige SQL Client-verbinding is.
Deze waarnemingen maken het eenvoudig om verbindingen te gebruiken die zijn brokered door de elastic database-clientbibliotheek voor Dapper.
Dit codevoorbeeld (uit het bijbehorende voorbeeld) illustreert de benadering waarbij de shardingsleutel door de toepassing wordt geleverd aan de bibliotheek om de verbinding met de juiste shard te brokeren.
using (SqlConnection sqlconn = shardingLayer.ShardMap.OpenConnectionForKey(
key: tenantId1,
connectionString: connStrBldr.ConnectionString,
options: ConnectionOptions.Validate))
{
var blog = new Blog { Name = name };
sqlconn.Execute(@"
INSERT INTO
Blog (Name)
VALUES (@name)", new { name = blog.Name }
);
}
De aanroep van de Open Verbinding maken ionForKey-API vervangt het standaard maken en openen van een SQL Client-verbinding. De aanroep Open Verbinding maken ionForKey gebruikt de argumenten die vereist zijn voor gegevensafhankelijke routering:
- De shard-toewijzing voor toegang tot de gegevensafhankelijke routeringsinterfaces
- De shardingsleutel om de shardlet te identificeren
- De referenties (gebruikersnaam en wachtwoord) om verbinding te maken met de shard
Het shard-toewijzingsobject maakt een verbinding met de shard die de shardlet voor de opgegeven shardingsleutel bevat. De client-API's van de elastische database taggen ook de verbinding om de consistentiegaranties te implementeren. Aangezien de aanroep van Open Verbinding maken ionForKey een regelmatig SQL Client-verbindingsobject retourneert, volgt de volgende aanroep van de execute-extensiemethode van Dapper de standaard Dapper-praktijk.
Query's werken op dezelfde manier: u opent eerst de verbinding met Behulp van Open Verbinding maken ionForKey vanuit de client-API. Vervolgens gebruikt u de reguliere Dapper-extensiemethoden om de resultaten van uw SQL-query toe te wijzen aan .NET-objecten:
using (SqlConnection sqlconn = shardingLayer.ShardMap.OpenConnectionForKey(
key: tenantId1,
connectionString: connStrBldr.ConnectionString,
options: ConnectionOptions.Validate ))
{
// Display all Blogs for tenant 1
IEnumerable<Blog> result = sqlconn.Query<Blog>(@"
SELECT *
FROM Blog
ORDER BY Name");
Console.WriteLine("All blogs for tenant id {0}:", tenantId1);
foreach (var item in result)
{
Console.WriteLine(item.Name);
}
}
Houd er rekening mee dat het gebruiksblok met de DDR-verbindingsbereiken alle databasebewerkingen binnen het blok toekent aan de ene shard waar tenantId1 wordt bewaard. De query retourneert alleen blogs die zijn opgeslagen op de huidige shard, maar niet de blogs die zijn opgeslagen op andere shards.
Gegevensafhankelijke routering met Dapper en DapperExtensions
Dapper wordt geleverd met een ecosysteem van extra extensies die bij het ontwikkelen van databasetoepassingen meer gemak en abstractie van de database kunnen bieden. DapperExtensions is een voorbeeld.
Het gebruik van DapperExtensions in uw toepassing verandert niet hoe databaseverbindingen worden gemaakt en beheerd. Het is nog steeds de verantwoordelijkheid van de toepassing om verbindingen te openen en reguliere SQL Client-verbindingsobjecten worden verwacht door de extensiemethoden. We kunnen vertrouwen op de Open Verbinding maken ionForKey zoals hierboven wordt beschreven. Zoals in de volgende codevoorbeelden wordt weergegeven, is de enige wijziging dat u de T-SQL-instructies niet meer hoeft te schrijven:
using (SqlConnection sqlconn = shardingLayer.ShardMap.OpenConnectionForKey(
key: tenantId2,
connectionString: connStrBldr.ConnectionString,
options: ConnectionOptions.Validate))
{
var blog = new Blog { Name = name2 };
sqlconn.Insert(blog);
}
En dit is het codevoorbeeld voor de query:
using (SqlConnection sqlconn = shardingLayer.ShardMap.OpenConnectionForKey(
key: tenantId2,
connectionString: connStrBldr.ConnectionString,
options: ConnectionOptions.Validate))
{
// Display all Blogs for tenant 2
IEnumerable<Blog> result = sqlconn.GetList<Blog>();
Console.WriteLine("All blogs for tenant id {0}:", tenantId2);
foreach (var item in result)
{
Console.WriteLine(item.Name);
}
}
Tijdelijke fouten afhandelen
Het Microsoft Patterns &Practices-team heeft het toepassingsblok tijdelijke foutafhandeling gepubliceerd om toepassingsontwikkelaars te helpen veelvoorkomende tijdelijke foutvoorwaarden te beperken die optreden bij het uitvoeren in de cloud. Zie Perseverance, Secret of All Triumphs voor meer informatie: Het toepassingsblok voor tijdelijke foutafhandeling gebruiken.
Het codevoorbeeld is afhankelijk van de tijdelijke foutbibliotheek om te beschermen tegen tijdelijke fouten.
SqlDatabaseUtils.SqlRetryPolicy.ExecuteAction(() =>
{
using (SqlConnection sqlconn =
shardingLayer.ShardMap.OpenConnectionForKey(tenantId2, connStrBldr.ConnectionString, ConnectionOptions.Validate))
{
var blog = new Blog { Name = name2 };
sqlconn.Insert(blog);
}
});
SqlDatabaseUtils.SqlRetryPolicy in de bovenstaande code is gedefinieerd als een SqlDatabaseTransientErrorDetectionStrategy met maximaal 10 pogingen en een wachttijd van 5 seconden tussen de pogingen. Als u transacties gebruikt, moet u ervoor zorgen dat het bereik voor opnieuw proberen teruggaat naar het begin van de transactie in het geval van een tijdelijke fout.
Beperkingen
De in dit document beschreven methoden brengen een aantal beperkingen met zich mee:
- De voorbeeldcode voor dit document laat niet zien hoe u het schema voor shards beheert.
- Bij een aanvraag wordt ervan uitgegaan dat alle databaseverwerking ervan is opgenomen in één shard, zoals wordt geïdentificeerd door de shardingsleutel die door de aanvraag wordt verstrekt. Deze aanname houdt echter niet altijd vast, bijvoorbeeld wanneer het niet mogelijk is om een shardingsleutel beschikbaar te maken. Om dit te verhelpen, bevat de clientbibliotheek voor elastische databases de klasse MultiShardQuery. De klasse implementeert een verbindingsabstractie voor het uitvoeren van query's via verschillende shards. Het gebruik van MultiShardQuery in combinatie met Dapper valt buiten het bereik van dit document.
Conclusie
Toepassingen die gebruikmaken van Dapper en DapperExtensions kunnen eenvoudig profiteren van hulpprogramma's voor elastische databases voor Azure SQL Database. Via de stappen die in dit document worden beschreven, kunnen deze toepassingen de mogelijkheid van het hulpprogramma gebruiken voor gegevensafhankelijke routering door het maken en openen van nieuwe Sql Verbinding maken ion-objecten te wijzigen om de aanroep Open Verbinding maken ionForKey van de clientbibliotheek voor elastische databases te gebruiken. Hiermee worden de wijzigingen in de toepassing beperkt die nodig zijn voor die plaatsen waar nieuwe verbindingen worden gemaakt en geopend.
Aanvullende bronnen
Gebruikt u nog geen hulpprogramma's voor elastische databases? Bekijk de handleiding Aan de slag. Neem voor vragen contact met ons op op de microsoft Q&A-vragenpagina voor SQL Database en voor functieaanvragen, voeg nieuwe ideeën toe of stem op bestaande ideeën in het feedbackforum van SQL Database.
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor