Az Azure Core megosztott ügyfélkódtára a .NET-hez – 1.30.0-s verzió

Az Azure.Core megosztott primitíveket, absztrakciókat és segítőket biztosít a modern .NET Azure SDK-ügyfélkódtárakhoz. Ezek a kódtárak az Azure SDK .NET-hez készült tervezési irányelveit követik, és könnyen azonosíthatók csomag- és névterek nevei alapján az "Azure"-tól kezdve, például. Azure.Storage.Blobs Az Azure.Core-t használó ügyfélkódtárak teljesebb listája itt található.

Az Azure.Core lehetővé teszi az ügyfélkódtárak számára, hogy egységes módon tegyék elérhetővé a gyakori funkciókat, így ha megtanulja, hogyan használhatja ezeket az API-kat egy ügyfélkódtárban, tudni fogja, hogyan használhatja őket más ügyfélkódtárakban.

Forráskód | Csomag (NuGet) | API-referenciadokumentáció

Első lépések

Általában nem kell telepítenie az Azure.Core-t; akkor lesz telepítve, ha az egyik ügyfélkódtárat használja. Ha explicit módon szeretné telepíteni (például saját ügyfélkódtár implementálásához), itt találja a NuGet-csomagot.

Fő fogalmak

Az Azure.Core fő megosztott fogalmai (és így az Azure SDK-kódtárak az Azure.Core használatával) a következők:

• Szolgáltatásügyfelek konfigurálása, például újrapróbálkozások konfigurálása, naplózás (ClientOptions).
• A HTTP-válasz részleteinek elérése (Response, Response<T>).
• Hosszú ideig futó műveletek meghívása (Operation<T>).
• Lapozás és aszinkron streamek (AsyncPageable<T>).
• A szolgáltatáskérések hibáinak egységes módon történő jelentésére vonatkozó kivételek. (RequestFailedException).
• Kérés testreszabása (RequestContext).
• Absztrakciók az Azure SDK hitelesítő adatainak megadásához. (TokenCredentials).

Az alábbiakban a megosztott fogalmakat részletesebben ismertető szakaszokat talál.

Menetbiztonság

Garantáljuk, hogy minden ügyfélpéldány-metódus szálbiztos és független egymástól (iránymutatás). Ez biztosítja, hogy az ügyfélpéldányok újrafelhasználására vonatkozó javaslat mindig biztonságos legyen, még a szálak között is.

További fogalmak

Ügyfélbeállítások | A válasz | elérése Hosszú ideig futó műveletek | Hibák | kezelése Diagnosztika | Gúnyos | Ügyfélélettartam

Példák

MEGJEGYZÉS: A fájlban található minták csak az Azure SDK tervezési irányelveit követő csomagokra vonatkoznak. Az ilyen csomagok nevei általában a -vel kezdődnek Azure.

Szolgáltatásügyfelek konfigurálása a használatával ClientOptions

Az Azure SDK-ügyfélkódtárak általában egy vagy több szolgáltatásügyfél-típust fednek fel, amelyek a megfelelő Azure-szolgáltatások hívásának fő kiindulópontjai. Ezeket az ügyféltípusokat könnyen megtalálhatja, mivel nevük az Ügyfél szóra végződik. Használhatja például BlockBlobClient a Blob Storage szolgáltatás meghívására, és KeyClient Key Vault szolgáltatás titkosítási kulcsainak elérésére.

Ezek az ügyféltípusok egy egyszerű konstruktor meghívásával vagy a különböző konfigurációs beállításokat igénylő túlterheléssel hozhatók létre. Ezeket a beállításokat a rendszer paraméterként adja át, amely kibővíti ClientOptions az Azure.Core által közzétett osztályt. A különböző szolgáltatásspecifikus beállítások általában hozzá vannak adva az alosztályaihoz, de az SDK-szintű lehetőségek egy készlete közvetlenül a webhelyen ClientOptionsérhető el.

SecretClientOptions options = new SecretClientOptions()
{
    Retry =
    {
        Delay = TimeSpan.FromSeconds(2),
        MaxRetries = 10,
        Mode = RetryMode.Fixed
    },
    Diagnostics =
    {
        IsLoggingContentEnabled = true,
        ApplicationId = "myApplicationId"
    }
};

SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential(), options);

További információ az ügyfélkonfigurációs minták ügyfélkonfigurációjáról

HTTP-válasz részleteinek elérése a használatával Response<T>

A szolgáltatásügyfelek olyan módszerekkel rendelkeznek, amelyekkel meghívhatók az Azure-szolgáltatások. Ezekre az ügyfélmetaképpeni szolgáltatásmódszerekre hivatkozunk. A szolgáltatási metódusok megosztott Azure.Core-típust Response<T> adnak vissza (ritka esetekben nem általános testvére, nyers Response). Ez a típus hozzáférést biztosít mind a szolgáltatáshívás deszerializált eredményéhez, mind a kiszolgálótól kapott HTTP-válasz részleteihez.

// create a client
var client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// call a service method, which returns Response<T>
Response<KeyVaultSecret> response = await client.GetSecretAsync("SecretName");

// Response<T> has two main accessors.
// Value property for accessing the deserialized result of the call
KeyVaultSecret secret = response.Value;

// .. and GetRawResponse method for accessing all the details of the HTTP response
Response http = response.GetRawResponse();

// for example, you can access HTTP status
int status = http.Status;

// or the headers
foreach (HttpHeader header in http.Headers)
{
    Console.WriteLine($"{header.Name} {header.Value}");
}

További információ a választípusokról a válaszmintákban

Konzolnaplózás beállítása

Ha olyan Azure SDK-naplófigyelőt szeretne létrehozni, amely üzeneteket ad ki a konzolon, használja AzureEventSourceListener.CreateConsoleLogger a metódust.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

További információ a diagnosztikai mintákba való bejelentkezésről

Jelentéskészítési hibák RequestFailedException

Ha egy szolgáltatáshívás meghiúsul Azure.RequestFailedException , a szolgáltatáshívás ki lesz dobva. A kivétel típusa egy Status tulajdonságot biztosít EGY HTTP-állapotkóddal és egy Szolgáltatásspecifikus hibakóddal rendelkező ErrorCode tulajdonsággal.

try
{
    KeyVaultSecret secret = client.GetSecret("NonexistentSecret");
}
// handle exception with status code 404
catch (RequestFailedException e) when (e.Status == 404)
{
    // handle not found error
    Console.WriteLine("ErrorCode " + e.ErrorCode);
}

További információ a válaszok válaszmintákban való kezeléséről

Szolgáltatásmódszerek felhasználása – visszaadva AsyncPageable<T>

Ha egy szolgáltatáshívás több értéket ad vissza a lapokban, az eredményül ad vissza Pageable<T>/AsyncPageable<T> . Az iterálást AsyncPageable közvetlenül vagy lapokban végezheti el.

// call a service method, which returns AsyncPageable<T>
AsyncPageable<SecretProperties> allSecretProperties = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecretProperties)
{
    Console.WriteLine(secretProperties.Name);
}

A lapozható válaszokról további információt a .NET-hez készült Azure SDK-val való lapozás című témakörben talál.

Long-Running műveletek használata Operation<T>

Egyes műveletek végrehajtása hosszú időt vesz igénybe, és az állapotuk lekérdezését igényli. A hosszú ideig futó műveleteket kezdő metódusok típusokat adnak vissza *Operation<T> .

A WaitForCompletionAsync metódussal egyszerűen megvárhatja a művelet befejezését, és lekérheti az eredményként kapott értéket.

// create a client
SecretClient client = new SecretClient(new Uri("http://example.com"), new DefaultAzureCredential());

// Start the operation
DeleteSecretOperation operation = await client.StartDeleteSecretAsync("SecretName");

Response<DeletedSecret> response = await operation.WaitForCompletionAsync();
DeletedSecret value = response.Value;

Console.WriteLine(value.Name);
Console.WriteLine(value.ScheduledPurgeDate);

További információ a hosszú ideig futó műveleti mintákban végzett hosszú távú műveletekről

Customzing Request Using RequestContext

A szolgáltatásügyfelek általános konfigurálása mellett ClientOptionslehetőség van a szolgáltatásügyfelek által küldött kérések testreszabására olyan protokollmódszerek vagy kényelmi API-k használatával, amelyek paraméterként lesznek közzétéve RequestContext .

var context = new RequestContext();
context.AddClassifier(404, isError: false);

Response response = await client.GetPetAsync("pet1", context);

További információ a kérés testreszabásáról a RequestContext-mintákban

Gúnyos

Az Azure.Core-t használó új ügyfélkódtárak egyik legfontosabb keresztvágási funkciója az, hogy ezeket a kódtárakat kigúnyolásra tervezték. A gúnyolást a következő engedélyezi:

• egy védett paraméter nélküli konstruktor biztosítása az ügyféltípusokon.
• virtuálissá teszi a szolgáltatásmódszereket.
• API-k biztosítása a virtuális szolgáltatás metódusaiból visszaadott modelltípusok létrehozásához. A gyári metódusok megkereséséhez keresse meg a ModelFactory utótaggal rendelkező típusokat, például: SecretModelFactory.

A ConfigurationClient.Get metódus például a következőképpen lehet kipockázni ( a Moq használatával):

// Create a mock response
var mockResponse = new Mock<Response>();

// Create a mock value
var mockValue = SecretModelFactory.KeyVaultSecret(
    SecretModelFactory.SecretProperties(new Uri("http://example.com"))
);

// Create a client mock
var mock = new Mock<SecretClient>();

// Setup client method
mock.Setup(c => c.GetSecret("Name", null, default))
    .Returns(Response.FromValue(mockValue, mockResponse.Object));

// Use the client mock
SecretClient client = mock.Object;
KeyVaultSecret secret = client.GetSecret("Name");

További információ a minták szimulálásával kapcsolatban

Elosztott nyomkövetés az Application Insights használatával

Az Application Insights az Azure Monitor egy olyan funkciója, amely egy bővíthető alkalmazásteljesítmény-kezelési (Application Performance Management, APM) szolgáltatás fejlesztők és DevOps-szakemberek számára. Ezzel figyelheti az élő alkalmazásokat. Automatikusan észleli a teljesítményanomáliákat, és hatékony elemzési eszközöket tartalmaz a problémák diagnosztizálásához és annak megértéséhez, hogy a felhasználók valójában mit csinálnak az alkalmazással

Ha az alkalmazás már használja az ApplicationInsightsot, az Azure SDK-nyomkövetések automatikus gyűjtése a verzió 2.12.0óta támogatott.

Az ApplicationInsights alkalmazáskövetés beállításához kövesse az Alkalmazásfigyelés indítása című útmutatót.

További információ a diagnosztikai minták diagnosztikájáról.

Hibaelhárítás

A hibák elhárításának három fő módja a kivételek vizsgálata, a naplózás engedélyezése és az elosztott nyomkövetés

Következő lépések

Fedezze fel és telepítse az elérhető Azure SDK-kódtárakat.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes adattárban a CLA használatával.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.