.NET SDK kapsayıcı oluşturmaya genel bakış
.NET uygulamalarını
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
:true
olarak ayarlayın. Bu özellik,console
,webapp
veworker
gibi yürütülebilir proje türleri için örtük olaraktrue
olarak ayarlanır. -
EnableSdkContainerSupport
: Proje türünüz bir konsol uygulaması olduğundatrue
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
/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 publish
kullanı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 DefaultContainer
olarak 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 push
işlevlerini yerine getiren tüm kayıt defterleriyle sorunsuz çalışmasını sağlamalıdır. Bu dosya normalde ~/.docker/config.json
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.conf
konumunda 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 true
olarak 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
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 true
olarak 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 , SelfContained veya 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_failure ise, gönderme veya çekme kayıt defterine mi yapıldı? |
push |
Hedef RID | Hata bir rid_mismatch ise, hangi RID istendi? |
linux-x64 |
Kullanılabilir RID'ler | Hata bir rid_mismatch ise, temel görüntü hangi RID'leri destekliyordu? |
linux-x64,linux-arm64 |
Ayrıca bkz.
- .NET uygulamalarını kapsayıcı olarak yayımlama
- .NET uygulama referansını kapsayıcılı hale getirme