.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 Azure
baş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 ClientOptions
kullanı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 ClientOptions
hizmet 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.0
Azure 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 .