.NET uygulama başvurularını kapsayıcıya alma

Bu başvuru makalesinde, bir .NET uygulamasını kapsayıcı olarak yayımladığınızda oluşturulan kapsayıcı görüntüsünü yapılandırmayı öğreneceksiniz. Bu makale, görüntüyü, yürütme ortamını ve kapsayıcı başlatıldığında çalıştırılacak komutları denetlemek için ayarlayabileceğiniz çeşitli özellikleri kapsar.

Kapsayıcı görüntüsünü yapılandırma

MSBuild özellikleri aracılığıyla oluşturulan kapsayıcının birçok yönünü denetleyebilirsiniz. Genel olarak, bir Dockerfile kullanarak bazı yapılandırmalar ayarlayabilirseniz, aynı işlemi MSBuild aracılığıyla da yapabilirsiniz.

.NET SDK ile RUN komutları gerçekleştirmenin hiçbir yolu yoktur. Bu komutlar genellikle bazı işletim sistemi paketlerini yüklemek veya yeni bir işletim sistemi kullanıcısı ya da herhangi bir sayıda rastgele şey oluşturmak için kullanılır. .NET SDK kapsayıcı oluşturma özelliğini kullanmaya devam etmek isterseniz, bunun yerine bu değişikliklerle özel bir temel görüntü oluşturabilir ve ardından bu temel görüntüyü kullanabilirsiniz. Daha fazla bilgi için bkz. ContainerBaseImage.

ContainerArchiveOutputPath

tar.gz arşivinde kapsayıcı görüntüsü oluşturmak için ContainerArchiveOutputPath özelliğini kullanın. Bu özellik, iş akışınız basit değilse ve örneğin resimlerinizi göndermeden önce bir tarama aracı çalıştırmanızı gerektiriyorsa kullanışlıdır. Arşiv oluşturulduktan sonra taşıyabilir, tarayabilir veya yerel bir Docker araç zincirine yükleyebilirsiniz.

Arşivde yayımlamak için ContainerArchiveOutputPath özelliğini dotnet publish komutunuza ekleyin, örneğin:

dotnet publish \
  -p PublishProfile=DefaultContainer \
  -p ContainerArchiveOutputPath=./images/sdk-container-demo.tar.gz

Belirli bir dosya adına sahip bir klasör adı veya yol belirtebilirsiniz. Klasör adını belirtirseniz, görüntü arşiv dosyası için oluşturulan dosya adı $(ContainerRepository).tar.gzolarak adlandırılır. Bu arşivler, yalnızca tüm ContainerImageTagsiçin tek bir dosya oluşturulduğu için içinde birden çok etiket içerebilir.

Kapsayıcı görüntüsü adlandırma yapılandırması

Kapsayıcı görüntüleri belirli bir adlandırma kuralına uyar. Görüntünün adı birkaç bölümden, kayıt defterinden, isteğe bağlı bağlantı noktasından, depodan ve isteğe bağlı etiket ve aileden oluşur.

REGISTRY[:PORT]/REPOSITORY[:TAG[-FAMILY]]

Örneğin, tam mcr.microsoft.com/dotnet/runtime:8.0-alpine görüntü adını göz önünde bulundurun:

• mcr.microsoft.com kayıt defteridir (ve bu örnekte Microsoft kapsayıcı kayıt defterini temsil eder).
• dotnet/runtime depodur (ancak bazıları bunu user/repository).
• 8.0-alpine etiket ve ailedir (aile, işletim sistemi paketlemesini belirsizleştirmeye yardımcı olan isteğe bağlı bir tanımlayıcıdır).

Aşağıdaki bölümlerde açıklanan bazı özellikler, oluşturulan görüntü adının bölümlerini yönetmeye karşılık gelir. Görüntü adı ile derleme özellikleri arasındaki ilişkiyi eşleyen aşağıdaki tabloyu göz önünde bulundurun:

Aşağıdaki bölümlerde, oluşturulan kapsayıcı görüntüsünü denetlemek için kullanılabilecek çeşitli özellikler açıklanmaktadır.

ContainerBaseImage

Kapsayıcı temel görüntüsü özelliği, görüntünüz için temel olarak kullanılan görüntüyü denetler. Varsayılan olarak, projenizin özelliklerine göre aşağıdaki değerler çıkarılır:

• Projeniz kendi içindeyse, temel görüntü olarak mcr.microsoft.com/dotnet/runtime-deps görüntüsü kullanılır.
• Projeniz bir ASP.NET Core projesiyse, temel görüntü olarak mcr.microsoft.com/dotnet/aspnet görüntüsü kullanılır.
• Aksi takdirde mcr.microsoft.com/dotnet/runtime görüntüsü temel görüntü olarak kullanılır.

Görüntünün etiketi, seçtiğiniz TargetFrameworksayısal bileşeni olarak çıkarılır. Örneğin, net6.0 hedefleyen bir proje, çıkarsanan temel görüntünün 6.0 etiketine neden olur ve net7.0-linux bir proje 7.0 etiketini kullanır vb.

Burada bir değer ayarlarsanız, tercih ettiğiniz herhangi bir etiket de dahil olmak üzere temel olarak kullanılacak görüntünün tam adını ayarlamanız gerekir:

<PropertyGroup>
    <ContainerBaseImage>mcr.microsoft.com/dotnet/runtime:8.0</ContainerBaseImage>
</PropertyGroup>

.NET SDK sürüm 8.0.200 ile, boyutu ve güvenliği iyileştirmek için ContainerBaseImage çıkarımı iyileştirilir:

• linux-musl-x64 veya linux-musl-arm64 Çalışma Zamanı Tanımlayıcılarını hedeflemek, projenizin çalıştığından emin olmak için alpine görüntü değişkenlerini otomatik olarak seçer:
  • Proje PublishAot=true kullanıyorsa en iyi boyut ve güvenlik için temel görüntünün nightly/runtime-depsjammy-chiseled-aot değişkeni.
  • Proje InvariantGlobalization=false kullanıyorsa, yerelleştirmenin hala çalıştığından emin olmak için -extra değişkenleri kullanılır.

Görüntü değişkenlerinin boyutları ve özellikleri hakkında daha fazla bilgi için bkz. .NET 8.0 Kapsayıcı Görüntüsü Boyutu Raporu.

ContainerFamily

.NET 8'den başlayarak ContainerFamily MSBuild özelliğini kullanarak uygulamanızın temel görüntüsü olarak Microsoft tarafından sağlanan farklı kapsayıcı görüntüleri ailesini seçebilirsiniz. Bu değer ayarlandığında, seçilen TFM'ye özgü etiketin sonuna eklenir ve sağlanan etiket değiştirilir. Örneğin, .NET temel görüntülerinin Alpine Linux değişkenlerini kullanmak için ContainerFamilyalpineolarak ayarlayabilirsiniz:

<PropertyGroup>
    <ContainerFamily>alpine</ContainerFamily>
</PropertyGroup>

Yukarıdaki proje yapılandırması, .NET 8'i hedefleyen bir uygulama için son 8.0-alpine etiketine neden olur.

Bu alan serbest biçimlidir ve genellikle farklı işletim sistemi dağıtımlarını, varsayılan paket yapılandırmalarını veya temel görüntüdeki değişikliklerin diğer tür seçmek için kullanılabilir. ContainerBaseImage ayarlandığında bu alan yoksayılır. Daha fazla bilgi için bkz. .NET kapsayıcı görüntülerini.

ContainerRuntimeIdentifier(s)

ContainerRuntimeIdentifier özelliği, ContainerBaseImage birden çok platformu destekliyorsa kapsayıcınızın işletim sistemini ve mimarisini belirtir. Örneğin, mcr.microsoft.com/dotnet/runtime görüntüsü linux-x64, linux-arm, linux-arm64ve win10-x64destekler. Varsayılan olarak, kapsayıcı yayımlanırken kullanılan RuntimeIdentifier ayarlanır. Genellikle bu özelliği açıkça ayarlamanız gerekmez; bunun yerine, -r komutuyla dotnet publish seçeneğini kullanın. Seçilen görüntü belirtilen RuntimeIdentifierdesteklemiyorsa, desteklenen tanımlayıcıları bir hata gösterir.

Bu özelliği kullanmak zorunda kalmamak için, ContainerBaseImage özelliğini istediğiniz zaman etiketi de dahil olmak üzere tam resim adına ayarlayabilirsiniz.

<PropertyGroup>
    <ContainerRuntimeIdentifier>linux-arm64</ContainerRuntimeIdentifier>
</PropertyGroup>

Çok mimarili görüntüler için birden çok kapsayıcı çalışma zamanı tanımlayıcısı belirtmek için, ContainerRuntimeIdentifiers özelliğinde birden çok TargetFrameworksayarlamaya benzer şekilde noktalı virgülle ayrılmış bir çalışma zamanı tanımlayıcısı kümesi kullanın:

<PropertyGroup>
    <ContainerRuntimeIdentifiers>linux-x64;linux-arm64</ContainerRuntimeIdentifiers>
</PropertyGroup>

.NET tarafından desteklenen çalışma zamanı tanımlayıcıları hakkında daha fazla bilgi için bkz. RID kataloğu.

ContainerRegistry

Kapsayıcı kayıt defteri özelliği, yeni oluşturulan görüntünün gönderileceği hedef kayıt defterini denetler. Varsayılan olarak yerel Docker daemon'a gönderilir, ancak bir uzak kayıt defteri de belirtebilirsiniz. Kimlik doğrulaması gerektiren bir uzak kayıt defteri kullanırken, iyi bilinen docker login mekanizmalarını kullanarak kimlik doğrulaması yaparsınız. Daha fazla bilgi için bkz. Kapsayıcı kayıt defterlerinde kimlik doğrulaması daha fazla ayrıntı için. Bu özelliği kullanmanın somut bir örneği için aşağıdaki XML örneğini göz önünde bulundurun:

<PropertyGroup>
    <ContainerRegistry>registry.mycorp.com:1234</ContainerRegistry>
</PropertyGroup>

Bu araç, Docker Kayıt Defteri HTTP API V2destekleyen herhangi bir kayıt defterinde yayımlamayı destekler. Bu, aşağıdaki kayıt defterlerini açıkça (ve büyük olasılıkla daha örtük olarak) içerir:

• Azure Container Registry
• Amazon Elastic Container Registry
• Google Artifact Registry
• Docker Hub
• GitHub Packages
• GitLab tarafından barındırılan Container Registry
• Quay.io

Bu kayıt defterleriyle çalışma hakkında notlar için,kayıt defterine özgü notlarına bakın.

ContainerRepository

Kapsayıcı deposu görüntünün adıdır, örneğin dotnet/runtime veya my-app. Varsayılan olarak, projenin AssemblyName kullanılır.

<PropertyGroup>
    <ContainerRepository>my-app</ContainerRepository>
</PropertyGroup>

Görüntü adları, her biri yalnızca küçük harfli alfasayısal karakterler, nokta, alt çizgi ve tire içerebilen ve harf veya sayı ile başlaması gereken bir veya daha fazla eğik çizgiyle ayrılmış kesimden oluşur. Diğer karakterler hatayla sonuçlanır.

ContainerImageTag(s)

Kapsayıcı görüntüsü etiketi özelliği, görüntü için oluşturulan etiketleri denetler. Tek bir etiket belirtmek için ContainerImageTag ve birden çok etiket için ContainerImageTagskullanın.

Etiketler genellikle bir uygulamanın farklı sürümlerine başvurmak için kullanılır, ancak farklı işletim sistemi dağıtımlarına, hatta farklı yapılandırmalara da başvurabilir.

.NET 8'den başlayarak, bir etiket sağlanmayan varsayılan değer latest.

Varsayılanı geçersiz kılmak için aşağıdakilerden birini belirtin:

<PropertyGroup>
    <ContainerImageTag>1.2.3-alpha2</ContainerImageTag>
</PropertyGroup>

Birden çok etiket belirtmek için, ContainerImageTags özelliğinde birden çok TargetFrameworksayarlamaya benzer şekilde noktalı virgülle ayrılmış bir etiket kümesi kullanın:

<PropertyGroup>
    <ContainerImageTags>1.2.3-alpha2;latest</ContainerImageTags>
</PropertyGroup>

Etiketler en fazla 127 alfasayısal karakter, nokta, alt çizgi ve tire içerebilir. Alfasayısal karakter veya alt çizgi ile başlamalıdır. Diğer formlar bir hatanın oluşmasına neden olur.

dotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerImageTags=`"1.2.3-alpha2`;latest`"

dotnet publish --os linux --arch x64 /t:PublishContainer /p:ContainerImageTags=\"1.2.3-alpha2;latest\"

$Env:ContainerImageTags='1.2.3;latest'; dotnet publish --os linux --arch x64 /t:PublishContainer

ContainerLabel

Kapsayıcı etiketi kapsayıcıya bir meta veri etiketi ekler. Etiketler genellikle güvenlik tarayıcıları ve diğer altyapı araçları tarafından kullanılmak üzere sürüm ve yazma meta verilerini depolamak için kullanılır. İstediğiniz sayıda kapsayıcı etiketi belirtebilirsiniz.

ContainerLabel düğümünde iki öznitelik vardır:

• Include: Etiketin anahtarı.
• Value: Etiketin değeri (bu boş olabilir).

<ItemGroup>
    <ContainerLabel Include="org.contoso.businessunit" Value="contoso-university" />
</ItemGroup>

Varsayılan olarak oluşturulan etiketlerin listesi için bkz.varsayılan kapsayıcı etiketleri .

Kapsayıcı yürütmeyi yapılandırma

Kapsayıcının yürütülmesini denetlemek için aşağıdaki MSBuild özelliklerini kullanabilirsiniz.

ContainerWorkingDirectory

Kapsayıcı çalışma dizini düğümü, kapsayıcının çalışma dizinini denetler; başka komut çalıştırılmazsa komutların içinde yürütülür.

Varsayılan olarak, çalışma dizini olarak /app dizin değeri kullanılır.

<PropertyGroup>
    <ContainerWorkingDirectory>/bin</ContainerWorkingDirectory>
</PropertyGroup>

ContainerPort

Kapsayıcı bağlantı noktası, kapsayıcı için bilinen bağlantı noktaları listesine İletim Denetimi Protokolü (TCP) veya Kullanıcı Veri Birimi Protokolü (UDP) bağlantı noktalarını ekler. Bu, Docker gibi kapsayıcı çalışma zamanlarının bu bağlantı noktalarını otomatik olarak konak makinesine eşlemesini sağlar. Bu genellikle kapsayıcı için belge olarak kullanılır, ancak otomatik bağlantı noktası eşlemesini etkinleştirmek için de kullanılabilir.

ContainerPort düğümünde iki öznitelik vardır:

• Include: Kullanıma sunma bağlantı noktası numarası.
• Type: varsayılan olarak tcp, geçerli değerler tcp veya udp.

<ItemGroup>
    <ContainerPort Include="80" Type="tcp" />
</ItemGroup>

.NET 8'den başlayarak, ContainerPort, birçok iyi bilinen ASP.NET ortam değişkenine göre açıkça sağlanmadığında çıkarılır:

• ASPNETCORE_URLS
• ASPNETCORE_HTTP_PORTS
• ASPNETCORE_HTTPS_PORTS

Bu ortam değişkenleri varsa, değerleri ayrıştırılır ve TCP bağlantı noktası eşlemelerine dönüştürülür. Bu ortam değişkenleri, varsa temel görüntünüzden veya projenizde tanımlanan ortam değişkenlerinden ContainerEnvironmentVariable öğeler aracılığıyla okunur. Daha fazla bilgi için bkz. ContainerEnvironmentVariable.

ContainerEnvironmentVariable

Kapsayıcı ortam değişkeni düğümü, kapsayıcıya ortam değişkenleri eklemenize olanak tanır. Ortam değişkenleri kapsayıcıda çalışan uygulama tarafından hemen erişilebilir ve genellikle çalışan uygulamanın çalışma zamanı davranışını değiştirmek için kullanılır.

ContainerEnvironmentVariable düğümünde iki öznitelik vardır:

• Include: Ortam değişkeninin adı.
• Value: Ortam değişkeninin değeri.

<ItemGroup>
  <ContainerEnvironmentVariable Include="LOGGER_VERBOSITY" Value="Trace" />
</ItemGroup>

Daha fazla bilgi için bkz. .NET ortam değişkenlerini.

Kapsayıcı komutlarını yapılandırma

Varsayılan olarak, kapsayıcı araçları uygulamanız için oluşturulan AppHost ikili dosyasını (uygulamanız bir AppHost kullanıyorsa) veya dotnet komutunu ve uygulamanızın DLL'sini kullanarak uygulamanızı başlatır.

Ancak, ContainerAppCommand, ContainerAppCommandArgs, ContainerDefaultArgsve ContainerAppCommandInstructionbirleşimini kullanarak uygulamanızın nasıl yürütülebileceğini denetleyebilirsiniz.

Farklı temel görüntüler kapsayıcı ENTRYPOINT ve COMMAND özelliklerinin farklı bileşimlerini kullandığından ve bunların tümünü destekleyebilmek istediğinizden bu farklı yapılandırma noktaları vardır. Varsayılanlar çoğu uygulama için kullanılabilir olmalıdır, ancak uygulama başlatma davranışınızı özelleştirmek istiyorsanız şunları yapmalısınız:

• Çalıştırılacak ikiliyi belirleyin ve ContainerAppCommand olarak ayarlayın
• Uygulamanızın çalışması için hangi bağımsız değişkenlerin gerekli olduğunu belirleyin ve bunları ContainerAppCommandArgs olarak ayarlayın
• Hangi bağımsız değişkenlerin (varsa) isteğe bağlı olduğunu ve kullanıcı tarafından geçersiz kılınabileceğini belirleyin ve bunları ContainerDefaultArgs olarak ayarlayın
• ContainerAppCommandInstruction DefaultArgs olarak ayarlama

Daha fazla bilgi için aşağıdaki yapılandırma öğelerine bakın.

ContainerAppCommand

Uygulama komut yapılandırma öğesi, uygulamanızın mantıksal giriş noktasıdır. Çoğu uygulama için bu AppHost, uygulamanız için oluşturulan yürütülebilir ikili dosyadır. Uygulamanız bir AppHost oluşturmuyorsa, bu komut genellikle dotnet <your project dll>. Bu değerler, temel kapsayıcınızdaki herhangi bir ENTRYPOINT sonra veya doğrudan ENTRYPOINT tanımlanmadıysa uygulanır.

ContainerAppCommand yapılandırması, entrypoint komutunda kullanılacak komutu, seçeneği veya bağımsız değişkeni temsil eden tek bir Include özelliğine sahiptir:

<ItemGroup Label="ContainerAppCommand Assignment">
  <!-- This is how you would start the dotnet ef tool in your container -->
  <ContainerAppCommand Include="dotnet" />
  <ContainerAppCommand Include="ef" />

  <!-- This shorthand syntax means the same thing, note the semicolon separating the tokens. -->
  <ContainerAppCommand Include="dotnet;ef" />
</ItemGroup>

ContainerAppCommandArgs

Bu uygulama komutu args yapılandırma öğesi, uygulamanız için ContainerAppCommanduygulanması gereken mantıksal olarak gerekli bağımsız değişkenleri temsil eder. Varsayılan olarak, bir uygulama için hiçbiri oluşturulmaz. Mevcut olduğunda, bağımsız değişkenler çalıştırıldığında kapsayıcınıza uygulanır.

ContainerAppCommandArgs yapılandırması, Include komutuna uygulanacak seçeneği veya bağımsız değişkeni temsil eden tek bir ContainerAppCommand özelliğine sahiptir.

<ItemGroup>
  <!-- Assuming the ContainerAppCommand defined above,
       this would be the way to force the database to update.
  -->
  <ContainerAppCommandArgs Include="database" />
  <ContainerAppCommandArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerAppCommandArgs Include="database;update" />
</ItemGroup>

ContainerDefaultArgs

Bu varsayılan bağımsız yapılandırma öğesi, uygulamanız için kullanıcı tarafından geçersiz kılınabilir bağımsız değişkenleri temsil eder. Bu, uygulamanızın başlatmayı ve yine de özelleştirmeyi kolaylaştıran bir şekilde çalışması gerekebilecek varsayılan değerler sağlamanın iyi bir yoludur.

ContainerDefaultArgs yapılandırması, Include komutuna uygulanacak seçeneği veya bağımsız değişkeni temsil eden tek bir ContainerAppCommand özelliğine sahiptir.

<ItemGroup>
  <!-- Assuming the ContainerAppCommand defined above,
       this would be the way to force the database to update.
  -->
  <ContainerDefaultArgs Include="database" />
  <ContainerDefaultArgs Include="update" />

  <!-- This is the shorthand syntax for the same idea -->
  <ContainerDefaultArgs Include="database;update" />
</ItemGroup>

ContainerAppCommandInstruction

Uygulama komut yönerge yapılandırması, kapsayıcıda çalıştırılan son komutu oluşturmak için ContainerEntrypoint, ContainerEntrypointArgs, ContainerAppCommand, ContainerAppCommandArgsve ContainerDefaultArgs birleştirilerek nasıl birleştirildiğini denetlemeye yardımcı olur. Bu, temel görüntüde bir ENTRYPOINT olup olmadığını büyük ölçüde bağlıdır. Bu özellik üç değerden birini alır: "DefaultArgs", "Entrypoint"veya "None".

• Entrypoint:
  • Bu modda, giriş noktası ContainerAppCommand, ContainerAppCommandArgsve ContainerDefaultArgstarafından tanımlanır.
• None:
  • Bu modda, giriş noktası ContainerEntrypoint, ContainerEntrypointArgsve ContainerDefaultArgstarafından tanımlanır.
• DefaultArgs:
  • Bu en karmaşık moddur; ContainerEntrypoint[Args] öğelerden hiçbiri yoksa, giriş noktası ve komutu oluşturmak için ContainerAppCommand[Args] ve ContainerDefaultArgs kullanılır. dotnet veya /usr/bin/dotnet sabit kodlanmış temel görüntülerin temel görüntü giriş noktası atlanır, böylece tam denetime sahip olursunuz.
  • Hem ContainerEntrypoint hem de ContainerAppCommand varsa, ContainerEntrypoint giriş noktası olur ve ContainerAppCommand komut olur.

ContainerUser

Kullanıcı yapılandırma özelliği, kapsayıcının çalıştığı varsayılan kullanıcıyı denetler. Bu genellikle kapsayıcıyı kök olmayan bir kullanıcı olarak çalıştırmak için kullanılır. Bu, güvenlik için en iyi yöntemdir. Bu yapılandırmanın dikkate alınması gereken birkaç kısıtlama vardır:

• Kullanıcı adı, Linux kullanıcı kimlikleri, grup adı, linux grup kimliği, username:groupnameve diğer kimlik varyantları gibi çeşitli formlar alabilir.
• Belirtilen kullanıcının veya grubun görüntüde var olduğuna dair bir doğrulama yoktur.
• Kullanıcının değiştirilmesi, özellikle Dosya Sistemi izinleri gibi konularda uygulamanın davranışını değiştirebilir.

Bu alanın varsayılan değeri proje TFM'sine ve hedef işletim sistemine göre değişir:

• .NET 8 veya üzerini hedefleyip Microsoft çalışma zamanı görüntülerini kullanıyorsanız:
  • Linux'ta köksüz kullanıcı app kullanılır (kullanıcı kimliği tarafından başvurulsa da)
  • Windows'ta köksüz kullanıcı ContainerUser kullanılır
• Aksi takdirde varsayılan ContainerUser kullanılmaz

<PropertyGroup>
  <ContainerUser>my-existing-app-user</ContainerUser>
</PropertyGroup>

Uygulamanızı kök kullanıcı olarak çalışacak şekilde yapılandırmak için ContainerUser özelliğini rootolarak ayarlayın. Proje dosyanıza aşağıdakileri ekleyin:

<PropertyGroup>
  <ContainerUser>root</ContainerUser>
</PropertyGroup>

Alternatif olarak, komut satırından dotnet publish çağırırken bu değeri ayarlayabilirsiniz:

dotnet publish -p ContainerUser=root

Varsayılan kapsayıcı etiketleri

Etiketler genellikle kapsayıcı görüntülerinde tutarlı meta veriler sağlamak için kullanılır. Bu paket, oluşturulan görüntülerin daha iyi korunabilmesini teşvik etmek için bazı varsayılan etiketler sağlar.

• org.opencontainers.image.created, DateTime.UtcNowgeçerli değerinin ISO 8601 biçimine ayarlanır.

Daha fazla bilgi için bkz. Var olan etiket altyapısının üzerine geleneksel etiketler uygulama.

Ayrıca bkz.

• dotnet publish ile bir .NET uygulamasını kapsayıcılı hale
• .NET kapsayıcı görüntülerini