Kaynak Oluşturucular

  • Makale
  • Okumak için 2 dakika

Bu makale, .NET Compiler Platform ("Roslyn") SDK'sı kapsamında birlikte .NET Compiler Platform genel bakış sağlar. Kaynak Oluşturucular, C# geliştiricilerinin derlenmiş olan kullanıcı kodunu incelemelerine ve kullanıcının derlemelerine eklenen yeni C# kaynak dosyalarını oluşturmalarına olanak sağlayan bir C# derleyici özelliğidir.

Kaynak Oluşturucu derleme sırasında çalışan ve kodunuzun geri kalanıyla birlikte derlenmiş ek kaynak dosyaları üretmek için programınızı inceleyen bir kod parçasıdır.

Kaynak Oluşturucu, C# geliştiricilerinin yazması gereken ve iki önemli işlem yapmanizi sağlayan yeni bir bileşen t t'dır:

  1. Derlenmiş olan tüm kullanıcı kodunu temsil eden bir derleme nesnesi alın. Bu nesne incelenmiş olabilir ve derlenmiş kodun söz dizimi ve semantik modelleriyle çalışan bir kod yazabilirsiniz. Aynı bugün çözümleyicilerde olduğu gibi.

  2. Derleme sırasında bir derleme nesnesine eklenilen C# kaynak dosyaları oluşturma. Başka bir deyişle, kod derlenmişken derlemeye giriş olarak ek kaynak kodu sebilirsiniz.

Bu iki şey bir araya geldiğinde Kaynak Oluşturucuları bu kadar kullanışlı hale gelir. Derleme sırasında derleyicinin derlediği tüm zengin meta verilerle kullanıcı kodunu inceler, sonra da C# kodunu analiz edilen verileri temel alan aynı derlemeye geri yayın! Roslyn Çözümleyicileri'ne aşinasanız Kaynak Oluşturucuları C# kaynak kodunu yayan çözümleyiciler olarak düşünebilirsiniz.

Kaynak oluşturucular, aşağıda görselleştirilmiş bir derleme aşaması olarak çalıştırıldı:

Kaynak oluşturmanın farklı bölümlerini açıklayan grafik

Kaynak Oluşturucu, derleyici .NET Standard çözümleyiciler tarafından yüklenen bir 2.0 derlemesidir. Bu, tüm bileşenlerin yüklen .NET Standard çalıştırılabilir olduğu ortamlarda kullanılabilir.

Genel senaryolar

Günümüzde, kullanıcı kodunu incelemeye ve günümüzde teknoloji tarafından kullanılan analize göre bilgi veya kod oluşturmaya yönelik üç genel yaklaşım vardır: çalışma zamanı yansıma, IL oluşturma ve MSBuild oluşturma. Kaynak Oluşturucular her yaklaşımda bir geliştirme olabilir. Çalışma zamanı yansıma, .NET'e uzun zaman önce eklenmiş olan güçlü bir teknolojidir. Bunu kullanmak için sayısız senaryo vardır. Çok yaygın bir senaryo, bir uygulama başlatıldığında kullanıcı kodu üzerinde analiz gerçekleştirmek ve bu verileri kullanarak bir şeyler oluşturmaktır.

Örneğin, ASP.NET Core hizmetiniz ilk kez çalıştırarak denetleyiciler ve razor sayfaları gibi şeyleri "bağlantı kuracak" şekilde tanımlandığınızı yapıları keşfeder. Bu, güçlü soyutlamalarla basit kodlar yazmanıza olanak sağlar ancak çalışma zamanında bir performans cezası getirir: Web hizmetiniz veya uygulama ilk kez başlatıldığında, kodunuzla ilgili bilgileri bulandıran tüm çalışma zamanı yansıma kodu çalışma zamanı çalıştırmayı bitirene kadar hiçbir isteği kabul etmez! Bu performans cezası çok büyük olsa da, kendi uygulamanıza kendinizi geliştirilene kadar sabit bir maliyettir.

Kaynak Oluşturucu ile, başlatmanın denetleyici bulma aşaması, kaynak kodunuzu analiz ederek ve uygulamanıza "bağlantı yapmak" için gereken kodu yayarak derleme zamanında ortaya çıktı. Bu, bugün çalışma zamanında 4.000 çalışma zamanında meydana gelen bir eylemin derleme zamanlarına ertelenerek daha hızlı başlangıç sürelerine neden olabilir. Kaynak Oluşturucular, türleri keşfetmek için çalışma zamanında yansımayla sınırlı olmayan yollarla performansı geliştirebilir. Bazı senaryolar derlemeden verileri MSBuild için C# görevinin (CSC olarak da adlandırılan) birden çok kez çağrılmesini içerir. Tahmin ediyor olabileceğiniz gibi, derleyiciyi birden çok kez çağırmanız, uygulamanızı derlemek için gereken toplam zamanı etkiler! Kaynak MSBuild oluşturucular yalnızca bazı performans avantajları sunmakla birlikte araçların doğru soyutlama düzeyinde çalışmasına da izin verir.

Kaynak Oluşturucular'ın sunabilirsiniz bir diğer özelliği de denetleyiciler ve razor sayfaları arasında yönlendirmenin nasıl ASP.NET Core gibi bazı "dize türünde" API'leri kullanmaktır. Kaynak Oluşturucu ile yönlendirme, derleme zamanı ayrıntısı olarak oluşturulan gerekli dizelerle kesin olarak yazabilirsiniz. Bu, yanlış türe sahip bir dize değişmez değerine sahip bir isteğin doğru denetleyiciye isabet sızma süresini azaltır.

Kullanmaya başlayın oluşturucularla birlikte

Bu kılavuzda API'yi kullanarak kaynak oluşturucu oluşturma adımlarını ISourceGenerator keşfedebilirsiniz.

  1. Bir .NET konsol uygulaması oluşturun.

  2. Program sınıfını aşağıdakiyle değiştirin:

    partial class Program
{
    static void Main(string[] args)
    {
        HelloFrom("Generated Code");
    }

    static partial void HelloFrom(string name);
}

    Not

    Bu örneği olduğu gibi çalıştır ancak henüz hiçbir şey olmaz.

  3. Ardından, yönteminin içeriğini dolduracak bir kaynak oluşturucu HelloFrom oluşturuz.

  4. Aşağıdakine benzer bir .NET standart kitaplık projesi oluşturun:

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="3.9.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.0.0" PrivateAssets="all" />
  </ItemGroup>

</Project>

  5. Kendi Kaynak Oluşturucu'larınızı belirten bir C# dosyası oluşturun veya şu şekilde oluşturun:

    using Microsoft.CodeAnalysis;

namespace MyGenerator
{
    [Generator]
    public class MySourceGenerator : ISourceGenerator
    {
        public void Execute(GeneratorExecutionContext context)
        {
            // Code generation goes here
        }

        public void Initialize(GeneratorInitializationContext context)
        {
            // No initialization required for this one
        }
    }
}

  6. yönteminin içeriğini Execute aşağıdaki gibi olacak şekilde değiştirin:

    public void Execute(GeneratorExecutionContext context)
{
    // find the main method
    var mainMethod = context.Compilation.GetEntryPoint(context.CancellationToken);

    // build up the source code
    string source = $@"
using System;

namespace {mainMethod.ContainingNamespace.ToDisplayString()}
{{
    public static partial class {mainMethod.ContainingType.Name}
    {{
        static partial void HelloFrom(string name)
        {{
            Console.WriteLine($""Generator says: Hi from '{{name}}'"");
        }}
    }}
}}
";
    // add the source code to the compilation
    context.AddSource("generatedSource", source);
}

  7. Artık çalışır bir oluşturucumuz var ancak bunu konsol uygulamamıza bağlamamız gerekiyor. Özgün konsol uygulaması projesini düzenleyin ve proje yolunu yukarıda oluşturduğunuz projeden .NET Standard değiştirerek şunları ekleyin:

      <!-- Add this as a new ItemGroup, replacing paths and names appropriately -->
  <ItemGroup>
    <!-- Note that this is not a "normal" ProjectReference.
         It needs the additional 'OutputItemType' and 'ReferenceOutputAssembly' attributes. -->
    <ProjectReference Include="path-to-sourcegenerator-project.csproj"
                      OutputItemType="Analyzer"
                      ReferenceOutputAssembly="false" />
  </ItemGroup>

  8. Şimdi konsol uygulamasını çalıştırarak oluşturulan kodun çalıştırılır ve ekrana yazdırılır.

    Not

    IntelliSense'i görmek ve erken Visual Studio deneyimiyle hatalardan kurtulmak için şu anda yeniden başlatmanız gerekir.

Sonraki adımlar

Kaynak Oluşturucular Kılavuzu, bu örneklerin bazılarına çözüm için önerilen yaklaşımlarla birlikte gider. Buna ek olarak, tek başına deneye GitHub bir dizi örneğimiz vardır.

Kaynak Oluşturucular hakkında daha fazla bilgi edinmek için şu konu başlıklarına bakın: