.NET için Azure Core paylaşılan istemci kitaplığı - sürüm 1.30.0

Azure.Core, modern .NET Azure SDK istemci kitaplıkları için paylaşılan temel öğeler, soyutlamalar ve yardımcılar sağlar. Bu kitaplıklar .NET için Azure SDK Tasarım Yönergeleri'ni izler ve 'Azure' ile başlayan paket ve ad alanları ad alanlarıyla kolayca tanımlanabilir. Örneğin. Azure.Storage.Blobs Azure.Core kullanan istemci kitaplıklarının daha eksiksiz bir listesini burada bulabilirsiniz.

Azure.Core, istemci kitaplıklarının ortak işlevleri tutarlı bir şekilde kullanıma sunmasına olanak tanır, böylece bu API'leri bir istemci kitaplığında kullanmayı öğrendikte bunları diğer istemci kitaplıklarında nasıl kullanacağınızı bilirsiniz.

Kaynak kodu | Paket (NuGet) | API başvuru belgeleri

Başlarken

Genellikle Azure.Core'u yüklemeniz gerekmez; bunu kullanarak istemci kitaplıklarından birini yüklediğinizde sizin için yüklenir. Açıkça yüklemek istiyorsanız (örneğin, kendi istemci kitaplığınızı uygulamak için) NuGet paketini burada bulabilirsiniz.

Önemli kavramlar

Azure.Core'un (ve Azure.Core kullanan Azure SDK kitaplıklarının) temel paylaşılan kavramları şunlardır:

• Hizmet istemcilerini yapılandırma, örneğin yeniden denemeleri yapılandırma, günlüğe kaydetme (ClientOptions).
• HTTP yanıt ayrıntılarına erişme (Response, Response<T>).
• Uzun süre çalışan işlemleri (Operation<T>) çağırma.
• Sayfalama ve zaman uyumsuz akışlar (AsyncPageable<T>).
• Hizmet isteklerinden gelen hataları tutarlı bir şekilde raporlamaya yönelik özel durumlar. (RequestFailedException).
• İsteği özelleştirme (RequestContext).
• Azure SDK kimlik bilgilerini temsil eden özetler. (TokenCredentials).

Aşağıda, bu paylaşılan kavramları daha ayrıntılı açıklayan bölümler bulabilirsiniz.

İş parçacığı güvenliği

Tüm istemci örneği yöntemlerinin iş parçacığı açısından güvenli ve birbirinden bağımsız olduğunu garanti ediyoruz (kılavuz). Bu, istemci örneklerini yeniden kullanma önerisinin iş parçacıkları arasında bile her zaman güvenli olmasını sağlar.

Ek kavramlar

İstemci seçenekleri | Yanıta | erişme Uzun süre çalışan işlemler | | Hataları işlemeTanılama | Alaycı | İstemci ömrü

Örnekler

NOT: Bu dosyadaki örnekler yalnızca Azure SDK Tasarım Yönergeleri'ne uyan paketler için geçerlidir. Bu tür paketlerin adları genellikle ile Azurebaşlar.

Kullanarak Hizmet İstemcilerini Yapılandırma ClientOptions

Azure SDK istemci kitaplıkları genellikle ilgili Azure hizmetlerini çağırmak için ana başlangıç noktası olan bir veya daha fazla hizmet istemci türünü kullanıma sunar. Adları İstemci sözcüğüyle biterken bu istemci türlerini kolayca bulabilirsiniz. Örneğin, BlockBlobClient blob depolama hizmetini çağırmak için kullanılabilir ve KeyClient Key Vault hizmet şifreleme anahtarlarına erişmek için kullanılabilir.

Bu istemci türleri basit bir oluşturucu çağrılarak veya çeşitli yapılandırma seçeneklerini alan aşırı yüklemesiyle örneklenebilir. Bu seçenekler, Azure.Core tarafından kullanıma sunulan sınıfı genişleten ClientOptions bir parametre olarak geçirilir. Hizmete özgü çeşitli seçenekler genellikle alt sınıflarına eklenir, ancak SDK genelindeki bir dizi seçenek doğrudan üzerinde ClientOptionskullanılabilir.

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);

İstemci yapılandırma örneklerinde istemci yapılandırması hakkında daha fazla bilgi

Kullanarak HTTP Yanıt Ayrıntılarına Erişme Response<T>

Hizmet istemcilerinin Azure hizmetlerini çağırmak için kullanılabilecek yöntemleri vardır. Bu istemci yöntemleri hizmet yöntemlerine başvuruyoruz. Hizmet yöntemleri paylaşılan bir Azure.Core türü Response<T> döndürür (nadir durumlarda genel olmayan eşdüzey, ham Response). Bu tür hem hizmet çağrısının seri durumdan çıkarılmış sonucuna hem de sunucudan döndürülen HTTP yanıtının ayrıntılarına erişim sağlar.

// 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}");
}

Yanıt örneklerindeki yanıt türleri hakkında daha fazla bilgi

Konsol günlüğünü ayarlama

Konsola ileti çıkışı veren bir Azure SDK günlük dinleyicisi oluşturmak için yöntemini kullanın AzureEventSourceListener.CreateConsoleLogger .

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

Tanılama örneklerinde günlüğe kaydetme hakkında daha fazla bilgi

Raporlama Hataları RequestFailedException

Bir hizmet çağrısı başarısız olduğunda Azure.RequestFailedException oluşturulur. Özel durum türü, HTTP durum kodu içeren bir Status özelliği ve hizmete özgü hata koduna sahip bir ErrorCode özelliği sağlar.

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);
}

Yanıt örneklerinde yanıtları işleme hakkında daha fazla bilgi

Geri Dönen Hizmet Yöntemlerini Kullanma AsyncPageable<T>

Bir hizmet çağrısı sayfalarda birden çok değer döndürürse sonuç olarak döndürülir Pageable<T>/AsyncPageable<T> . Doğrudan veya sayfalarda yineleme AsyncPageable yapabilirsiniz.

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

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

Sayfalandırılmış yanıtlar hakkında daha fazla bilgi için bkz. .NET için Azure SDK ile sayfalandırma.

kullanarak Long-Running İşlemleri Kullanma Operation<T>

Bazı işlemlerin tamamlanması uzun sürer ve durumlarının yoklanmasını gerektirir. Uzun süre çalışan işlemleri başlatan yöntemler dönüş türleri döndürür *Operation<T> .

WaitForCompletionAsync yöntemi, işlemin tamamlanmasını beklemenin ve sonuçta elde edilen değeri elde etmenin kolay bir yoludur.

// 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);

Uzun süre çalışan işlem örneklerinde uzun süre çalışan işlemler hakkında daha fazla bilgi

Kullanarak İsteği Özelleştirme RequestContext

aracılığıyla ClientOptionshizmet istemcilerinin genel yapılandırmasının yanı sıra, protokol yöntemlerini veya parametre olarak kullanıma sunan RequestContext kolaylık API'lerini kullanarak hizmet istemcileri tarafından gönderilen istekleri özelleştirmek de mümkündür.

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

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

RequestContext örneklerinde istek özelleştirmesi hakkında daha fazla bilgi

Sahte işlem

Azure.Core kullanan yeni istemci kitaplıklarımızın en önemli çapraz kesme özelliklerinden biri, sahte kullanım için tasarlanmış olmalarıdır. Sahte oluşturma şu şekilde etkinleştirilir:

• istemci türlerinde korumalı bir parametresiz oluşturucu sağlar.
• hizmet yöntemlerini sanal hale getirme.
• sanal hizmet yöntemlerinden döndürülen model türlerini oluşturmak için API'ler sağlama. Bu fabrika yöntemlerini bulmak için ModelFactory soneki ile türleri arayın; örneğin SecretModelFactory.

Örneğin ConfigurationClient.Get yöntemi aşağıdaki gibi taklit edilebilir ( Moq ile):

// 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");

Sahte örneklerde alay etme hakkında daha fazla bilgi

Application Insights ile dağıtılmış izleme

Azure İzleyici'nin bir özelliği olan Application Insights, geliştiricilere ve DevOps uzmanlarına yönelik genişletilebilir bir Uygulama Performans Yönetimi (APM) hizmetidir. Canlı uygulamalarınızı izlemek için bunu kullanın. Performans anomalilerini otomatik olarak algılar ve sorunları tanılamanıza ve kullanıcıların uygulamanızla gerçekte ne yaptığını anlamanıza yardımcı olacak güçlü analiz araçları içerir

Uygulamanız zaten ApplicationInsights kullanıyorsa sürümünden itibaren 2.12.0Azure SDK izlemelerinin otomatik olarak toplanması desteklenir.

Uygulamanız için ApplicationInsights izlemeyi ayarlamak için İzleme Uygulamasını Başlat kılavuzunu izleyin.

Tanılama örneklerinde tanılama hakkında daha fazla bilgi.

Sorun giderme

Hataları gidermenin üç ana yolu özel durumları incelemek, günlüğe kaydetmeyi ve dağıtılmış izlemeyi etkinleştirmektir

Sonraki adımlar

Kullanılabilir Azure SDK kitaplıklarını keşfedin ve yükleyin.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bunu CLA'mızı kullanarak tüm depolarda yalnızca bir kez yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .