Aracılığıyla paylaş


.NET SDK kapsayıcı oluşturmaya genel bakış

.NET uygulamalarını Dockerfileile kapsayıcılı hale getirmek mümkün olsa da, uygulamaları doğrudan .NET SDKile kapsayıcıya için cazip nedenler vardır. Bu makale, .NET SDK kapsayıcı oluşturma özelliğine genel bir bakış sağlar ve kapsayıcı kayıt defterlerinde telemetri, yayımlama konuları, derleme özellikleri ve kimlik doğrulaması ile ilgili ayrıntıları içerir.

Proje yayımlama konusunda dikkat edilmesi gerekenler

Artık bir .NET uygulamanız olduğuna göre, bunu kapsayıcı olarak yayımlayabilirsiniz. Bunu yapmadan önce dikkat edilmesi gereken birkaç önemli nokta vardır. .NET SDK 8.0.200 sürümünden önce, 📦 Microsoft.NET.Build.Containers NuGet paketine ihtiyacınız vardı. Kapsayıcı desteği varsayılan olarak dahil olduğundan .NET SDK sürüm 8.0.200 ve üzeri için bu paket gerekli değildir.

Bir .NET uygulamasını kapsayıcı olarak yayımlamayı etkinleştirmek için aşağıdaki derleme özellikleri gereklidir:

  • IsPublishable: trueolarak ayarlayın. Bu özellik, console, webappve workergibi yürütülebilir proje türleri için örtük olarak true olarak ayarlanır.
  • EnableSdkContainerSupport: Proje türünüz bir konsol uygulaması olduğunda true olarak ayarlayın.

SDK kapsayıcı desteğini açıkça etkinleştirmek için aşağıdaki proje dosyası parçacığını göz önünde bulundurun:

<PropertyGroup>
  <IsPublishable>true</IsPublishable>
  <EnableSdkContainerSupport>true</EnableSdkContainerSupport>
</PropertyGroup>

Geçişleri ve derleme özelliklerini yayımlama

Tüm .NET CLI komutlarında olduğu gibi,komut satırında MSBuild özelliklerini belirtebilirsiniz. Özellikler sağlamak için kullanılabilecek birçok geçerli söz dizimi formu vardır, örneğin:

  • /p:PropertyName=Value
  • -p:PropertyName=Value
  • -p PropertyName=Value
  • --property PropertyName=Value

Tercih ettiğiniz söz dizimini kullanabilirsiniz, ancak belgelerde -p formu kullanan örnekler gösterilir.

Bahşiş

Sorun gidermeye yardımcı olmak için MSBuid günlüklerini kullanmayı göz önünde bulundurun. İkili günlük (binlog) dosyası oluşturmak için -bl anahtarını dotnet publish komutuna ekleyin. Binlog dosyaları derleme sorunlarını tanılamak için yararlıdır ve MSBuild Structured Log Vieweriçinde açılabilir. Bunlar, MSBuild analizi için gerekli olan derleme işleminin ayrıntılı bir izlemesini sağlar. Daha fazla bilgi için bkz. Sorun giderme ve MSBuildiçin günlük oluşturma .

Profilleri ve hedefleri yayımlama

dotnet publishkullanırken, -p PublishProfile=DefaultContainer ile bir profil belirtmek, SDK'nın yayımlama işleminden sonra başka bir hedefi tetiklesine neden olan bir özellik ayarlayabilir. Bu, istenen sonucu elde etmenin dolaylı bir yoludur. Öte yandan, dotnet publish /t:PublishContainer kullanmak doğrudan PublishContainer hedefini çağırarak aynı sonuca ancak daha basit bir şekilde ulaşır.

Başka bir deyişle, aşağıdaki .NET CLI komutu:

dotnet publish -p PublishProfile=DefaultContainer

PublishProfile özelliğini DefaultContainerolarak ayarlayan, aşağıdaki komutla eşdeğerdir:

dotnet publish /t:PublishContainer

İki yöntem arasındaki fark, öncekinin özelliği ayarlamak için bir profil kullanması, ikincisi ise hedefi doğrudan çağırmasıdır. Bunun önemli olmasının nedeni, profillerin MSBuild'in bir özelliği olması ve özellikleri doğrudan ayarlamaktan daha karmaşık bir şekilde ayarlamak için kullanılabilmesidir.

Önemli sorunlardan biri, tüm proje türlerinin profilleri desteklememesi veya aynı profil kümesine sahip olmamasıdır. Ayrıca, Visual Studio ve .NET CLI gibi farklı araçlar arasında profil desteği düzeyinde bir farklılık vardır. Bu nedenle hedeflerin kullanılması genellikle aynı sonucu elde etmek için daha net ve daha yaygın olarak desteklenen bir yöntemdir.

Kapsayıcı kayıt defterleri için kimlik doğrulaması

Özel kapsayıcı kayıt defterleriyle etkileşime geçmek için bu kayıt defterleriyle kimlik doğrulaması yapılması gerekir.

Docker' ın docker login komutu aracılığıyla bununla oluşturulmuş bir deseni vardır. Bu, belirli kayıt defterleriyle kimlik doğrulaması için kurallar içeren bir Docker yapılandırma dosyasıyla etkileşim kurmanın bir yoludur. Bu dosya ve kodladığı kimlik doğrulama türleri, kayıt defteri kimlik doğrulaması için Microsoft.Net.Build.Containers tarafından desteklenir. Bu, paketin docker pull ve docker pushişlevlerini yerine getiren tüm kayıt defterleriyle sorunsuz çalışmasını sağlamalıdır. Bu dosya normalde ~/.docker/config.jsonkonumunda depolanır, ancak ek olarak config.json dosyası içeren bir dizine işaret eden değişkeni aracılığıyla belirtilebilir.

Kimlik doğrulama türleri

config.json dosyası üç tür kimlik doğrulaması içerir:

Açık kullanıcı adı/parola

config.json dosyasının auths bölümü, kayıt defteri adları ile Base64 kodlamalı kullanıcı adı:parola dizeleri arasında bir anahtar/değer eşlemesidir. Yaygın bir Docker senaryosunda, docker login <registry> -u <username> -p <password> çalıştırmak bu haritada yeni öğeler oluşturur. Bu kimlik bilgileri sürekli tümleştirme (CI) sistemlerinde popülerdir ve burada oturum açma işlemi çalıştırmanın başlangıcında belirteçler tarafından yapılır. Ancak, bir dosyada kimlik bilgilerinin çıplak olması güvenlik riski taşıdığı için son kullanıcılar için geliştirme makineleri arasında daha az popülerdir.

Kimlik doğrulama yardımcıları

config.json dosyasının credHelpers bölümü, kayıt defteri adları ile söz konusu kayıt defteri için kimlik bilgilerini oluşturmak ve almak için kullanılabilecek belirli programların adları arasında bir anahtar/değer eşlemesidir. Bu genellikle belirli kayıt defterleri karmaşık kimlik doğrulama gereksinimlerine sahip olduğunda kullanılır. Bu tür bir kimlik doğrulamasının çalışması için sisteminizin PATHüzerinde docker-credential-{name} adlı bir uygulamanız olmalıdır. Bu tür kimlik bilgileri güvenli olma eğilimindedir, ancak geliştirme veya CI makinelerinde ayarlanması zor olabilir.

Sistem anahtarlıkları

credsStore bölümü, sistemin parola yöneticisiyle arabirim kurabilen bir docker kimlik bilgisi yardımcı programının adını içeren tek bir dize özelliğidir. Windows için bu, örneğin wincred olabilir. Bunlar macOS ve Windows için Docker yükleyicileri arasında popülerdir.

Ortam değişkenleri aracılığıyla kimlik doğrulaması

Bazı senaryolarda, yukarıda açıklanan standart Docker kimlik doğrulama mekanizması yeterli gelmez. Bu araç, kayıt defterlerine kimlik bilgileri sağlamaya yönelik ek bir mekanizmaya sahiptir: ortam değişkenleri. Ortam değişkenleri kullanılıyorsa, kimlik bilgisi sağlama mekanizması hiç kullanılmaz. Aşağıdaki ortam değişkenleri desteklenir:

  • DOTNET_CONTAINER_REGISTRY_UNAME: Bu, kayıt defterinin kullanıcı adı olmalıdır. Kayıt defterinin parolası bir belirteçse, kullanıcı adı "<token>"olmalıdır.
  • DOTNET_CONTAINER_REGISTRY_PWORD: Bu, kayıt defteri için parola veya belirteç olmalıdır.

Not

.NET SDK 8.0.400 itibarıyla kapsayıcı işlemleri için ortam değişkenleri güncelleştirilmiştir. SDK_CONTAINER_* değişkenlerine artık DOTNET_CONTAINER_*ön eki eklenmiştir.

Bu mekanizma kimlik bilgisi sızıntısına karşı savunmasız olabilir, bu nedenle yalnızca diğer mekanizmanın kullanılamadığı senaryolarda kullanılmalıdır. Örneğin, bir Docker kapsayıcısının içinde SDK Container araçlarını kullanıyorsanız. Buna ek olarak, bu mekanizma ad alanı içinde değildir; hem kaynak kayıt defteri (temel görüntünüzün bulunduğu yer) hem de hedef kayıt defteri (son görüntünüzü göndereceğiniz yer) için aynı kimlik bilgilerini kullanmayı dener.

Güvenli olmayan kayıt defterlerini kullanma

Kayıt defteri erişiminin çoğunun güvenli olduğu varsayılır, yani kayıt defteriyle etkileşimde https kullanılır. Ancak, tüm kayıt defterleri TLS sertifikalarıyla yapılandırılmaz; özellikle vpn arkasındaki özel kurumsal kayıt defteri gibi durumlarda. Bu kullanım örneklerini desteklemek için kapsayıcı araçları, belirli bir kayıt defterinin güvenli olmayan iletişim kullandığını bildirmenin yollarını sağlar.

.NET 8.0.400'den başlayarak SDK bu yapılandırma dosyalarını ve biçimlerini anlar ve HTTP veya HTTPS kullanılması gerekip gerekmediğini belirlemek için bu yapılandırmayı otomatik olarak kullanır. Güvenli olmayan iletişim için kayıt defterinin yapılandırılması, seçtiğiniz kapsayıcı aracına göre değişir.

Docker

Docker, kayıt defteri yapılandırmasını daemon yapılandırmasındadepolar. Yeni güvenli olmayan kayıt defterleri eklemek için, "insecure-registries" dizisi özelliğine yeni konaklar eklenir:

{
  "insecure-registries": [
    "registry.mycorp.net"
  ]
}

Not

Bu dosyaya herhangi bir değişiklik uygulamak için Docker daemon'unu yeniden başlatmanız gerekir.

Podman

Podman, kayıt defteri bağlantı bilgilerini depolamak için bir registries.conf TOML dosyası kullanır. Bu dosya genellikle /etc/containers/registries.confkonumunda bulunur. Yeni güvenli olmayan kayıt defterleri eklemek için, kayıt defteri ayarlarını tutmak için bir TOML bölümü eklenir, ardından insecure seçeneği trueolarak ayarlanmalıdır.

[[registry]]
location = "registry.mycorp.net"
insecure = true

Not

registries.conf dosyasındaki değişiklikleri uygulamak için Podman'ı yeniden başlatmanız gerekir.

Ortam değişkenleri

9.0.100'den itibaren .NET SDK, DOTNET_CONTAINER_INSECURE_REGISTRIES ortam değişkeni aracılığıyla geçirilen güvenli olmayan kayıt defterlerini tanır. Bu değişken, yukarıdaki Docker ve Podman örnekleriyle aynı şekilde güvenli olmayan etki alanlarının virgülle ayrılmış bir listesini alır.

$Env:DOTNET_CONTAINER_INSECURE_REGISTRIES=localhost:5000,registry.mycorp.com; dotnet publish -t:PublishContainer -p:ContainerRegistry=registry.mycorp.com -p:ContainerBaseImage=localhost:5000/dotnet/runtime:9.0

Telemetri

Bir .NET uygulamasını kapsayıcı olarak yayımladığınızda, .NET SDK kapsayıcısı araçları araçların nasıl kullanıldığı hakkında kullanım telemetrisi toplar ve gönderir. Toplanan veri, .NET CLItarafından gönderilen telemetriye ek olarak sunulmaktadır, ancak aynı mekanizmaları kullanır ve önemli bir şekilde aynı devre dışı bırakma denetimlerineuymaktadır.

Toplanan telemetrinin doğası gereği genel olması ve kişisel bilgilerin sızdırılmaması amaçlanmıştır; amaç aşağıdakilerin ölçülmesi için tasarlanmıştır:

  • .NET SDK kapsayıcısı oluşturma özelliğinin genel kullanımı.
  • Başarı ve başarısızlık oranlarının yanı sıra en sık gerçekleşen hata türleri hakkında genel bilgiler.
  • Çeşitli kayıt defteri türlerine yayımlama veya yayımlamanın nasıl çağrıldığı gibi teknolojinin belirli özelliklerinin kullanımı.

Telemetriyi geri çevirmek için DOTNET_CLI_TELEMETRY_OPTOUT ortam değişkenini trueolarak ayarlayın. Daha fazla bilgi için bkz. .NET CLI telemetri.

Çıkarım telemetrisi

Temel görüntü çıkarım işleminin nasıl gerçekleştiği hakkında aşağıdaki bilgiler günlüğe kaydedilir:

Tarih noktası Açıklama Örnek değer
InferencePerformed Kullanıcılar temel görüntüleri el ile belirtiyor mu yoksa çıkarımdan mı yararlanıyor. true
TargetFramework Temel görüntü çıkarımı yaparken seçilen TargetFramework. net8.0
BaseImage Seçilen temel görüntünün değeri ancak yalnızca bu temel görüntünün Microsoft tarafından üretilen görüntülerden biri olması gerekir. Kullanıcı mcr.microsoft.com Üzerinde Microsoft tarafından üretilen görüntüler dışında herhangi bir görüntü belirtirse, bu değer null olur. mcr.microsoft.com/dotnet/aspnet
BaseImageTag Seçilen etiketin değeri, ancak yalnızca bu etiket Microsoft tarafından üretilen görüntülerden biri içinse. Kullanıcı mcr.microsoft.com Üzerinde Microsoft tarafından üretilen görüntüler dışında herhangi bir görüntü belirtirse, bu değer null olur. 8.0
ContainerFamily Bir kullanıcı temel görüntülerimizden birini 'flavor' seçmek için ContainerFamily özelliğini kullandıysa ContainerFamily özelliğinin değeri. Kullanıcı, mcr.microsoft.com adresinden Microsoft tarafından üretilmiş .NET görüntülerinden birini seçtiğinde veya çıkarsadığında bu yalnızca ayarlanır. jammy-chiseled
ProjectType Kapsayıcıya alınmakta olan proje türü. AspNetCore veya Console
PublishMode Uygulamanın nasıl paketlendiği. Aot, Trimmed, SelfContainedveya FrameworkDependent
IsInvariant Seçilen görüntü sabit genelleştirme gerektiriyorsa veya kullanıcı bunu el ile kabul ettiyse. true
TargetRuntime Bu uygulamanın yayımlandığı RID. linux-x64

Görüntü oluşturma telemetrisi

Kapsayıcı oluşturma ve yayımlama işleminin nasıl gerçekleştiği hakkında aşağıdaki bilgiler günlüğe kaydedilir:

Dönüm noktası Açıklama Örnek değer
RemotePullType Temel görüntü uzak bir kayıt defterinden geldiyse, ne tür bir kayıt defteriydi? Azure, AWS, Google, GitHub, DockerHub, MRC veya Diğer
LocalPullType Temel görüntü, kapsayıcı arka plan programı veya tarball gibi yerel bir kaynaktan geldiyse. Docker, Podman, Tarball
RemotePushType Görüntü uzak bir kayıt defterine gönderildiyse, ne tür bir kayıt defteriydi? Azure, AWS, Google, GitHub, DockerHub, MRC veya Diğer
LocalPushType Görüntü yerel bir hedefe gönderildiyse, ne gibi bir şeydi? Docker, Podman, Tarball

Ayrıca, işlem sırasında çeşitli hata türleri oluşursa, bu hataların türü hakkında veri toplandığı:

Tarih noktası Açıklama Örnek değer
Error Oluşan hata türü unknown_repository, credential_failure, rid_mismatch, local_load.
Direction Hata bir credential_failureise, gönderme veya çekme kayıt defterine mi yapıldı? push
Hedef RID Hata bir rid_mismatchise, hangi RID istendi? linux-x64
Kullanılabilir RID'ler Hata bir rid_mismatchise, temel görüntü hangi RID'leri destekliyordu? linux-x64,linux-arm64

Ayrıca bkz.