Delen via

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 SqlConnection-objecten te wijzigen om de Aanroep OpenConnectionForKey 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 koppelingen te maken tussen uw .NET-objecten en de parameters van SQL-instructies voor Execute aanroepen, of om de resultaten van uw SQL-query's te importeren in .NET-objecten met behulp van Query aanroepen vanuit 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 bij het communiceren met de clientbibliotheek voor elastische databases, die databaseverbindingen bemiddelt 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 shardkaart die wordt geleverd door de bibliotheek-API's. Deze mogelijkheid wordt shard-beheer genoemd. De shardkaart fungeert ook als makelaar van databaseverbindingen voor verzoeken die een sharding-sleutel bevatten. Deze mogelijkheid wordt aangeduid als gegevensafhankelijke routering.

Shard-kaarten en gegevensafhankelijke routering.

Met de shard-kaartbeheerder worden gebruikers beschermd tegen inconsistente weergaven in shardlet-gegevens die kunnen optreden wanneer gelijktijdige shardlet-beheerbewerkingen worden uitgevoerd op de databases. Hiervoor bemiddelen de shard-kaarten de databaseverbindingen voor een toepassing die met de bibliotheek is gebouwd. 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 OpenConnectionForKey-methode 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 via de shard map manager worden beheerd, 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 enDapperExtensions.

Technische richtlijnen

Gegevensafhankelijke routering met Dapper

Met Dapper is de toepassing doorgaans verantwoordelijk voor het maken en openen van de verbindingen met de onderliggende database. Gegeven een type T door de toepassing zal Dapper queryresultaten retourneren als .NET-verzamelingen van het type T. Dapper voert de toewijzing van de T-SQL-resultaatrijen uit 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 het reguliere SqlConnection-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 SqlConnection-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 worden bemiddeld 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 OpenConnectionForKey-API vervangt het standaard maken en openen van een SQL Client-verbinding. De aanroep OpenConnectionForKey gebruikt de argumenten die vereist zijn voor gegevensafhankelijke routering:

  • De shard-toewijzing voor toegang tot de gegevensafhankelijke routeringsinterfaces
  • De shardingsleutel om het shardlet te identificeren
  • De inloggegevens (gebruikersnaam en wachtwoord) om verbinding te maken met de shard

Het shard-kaartobject maakt 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 OpenConnectionForKey een normaal 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 OpenConnectionForKey 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);
            }
    }

Het using-blok met de DDR-verbindingskaders beperkt alle databasebewerkingen binnen het blok tot 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 OpenConnectionForKey zoals hierboven 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 een aantal nieuwe pogingen van 10 en 5 seconden wachttijd tussen nieuwe 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 benaderingen die in dit document worden beschreven, omvatten een aantal beperkingen:

  • De voorbeeldcode voor dit document laat niet zien hoe u het schema voor shards beheert.
  • Bij een verzoek gaan we ervan uit dat alle databaseverwerking ervan is opgenomen in één shard, zoals wordt geïdentificeerd door de shardingsleutel die door het verzoek wordt verstrekt. Deze aanname geldt echter niet altijd, bijvoorbeeld wanneer het niet mogelijk is om een shardingsleutel beschikbaar te stellen. 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 SqlConnection-objecten te wijzigen om de aanroep OpenConnectionForKey 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.

Verwante inhoud

Gebruikt u nog geen hulpprogramma's voor elastische databases? Bekijk onze Aan de slag-handleiding. 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 SQL Database-feedbackforum.