Aracılığıyla paylaş

Yalıtılmış çalışan modelinde C# Azure İşlevleri çalıştırma kılavuzu

Bu makalede yalıtılmış çalışan modelini kullanarak .NET Azure İşlevleri ile çalışma tanıtılmaktadır. Bu model, projenizin diğer çalışma zamanı bileşenlerinden bağımsız olarak .NET hedef sürümlerini oluşturmasına olanak tanır. Desteklenen belirli .NET sürümleri hakkında bilgi için bkz. supported version.

Yalıtılmış çalışan modeli işlevleri .NET oluşturmaya hemen başlamak için aşağıdaki bağlantıları kullanın.

Başlarken Kavramlar Örnekler

Yalıtılmış çalışan modeli projesini Azure dağıtma hakkında bilgi edinmek için bkz. Deploy to Azure İşlevleri.

Yalıtılmış çalışan modelinin avantajları

.NET sınıf kitaplığı işlevlerinizi iki modda çalıştırabilirsiniz: İşlevler konak çalışma zamanı ile aynı işlemde (in-process) veya yalıtılmış bir çalışan işlemde. .NET işlevleriniz yalıtılmış bir çalışan işleminde çalıştırıldığında aşağıdaki avantajlardan yararlanabilirsiniz:

  • Daha az çakışma: İşlevleriniz ayrı bir işlemde çalıştığından, uygulamanızda kullanılan derlemeler konak işlemi tarafından kullanılan aynı derlemelerin farklı sürümleriyle çakışmaz.
  • İşlemin tam denetimi: Uygulamanın başlatılmasını denetlersiniz, bu da kullanılan yapılandırmaları yönetebileceğiniz ve ara yazılımı başlatabileceğiniz anlamına gelir.
  • Standard bağımlılık ekleme: İşlemin tam denetimine sahip olduğunuzdan, bağımlılık ekleme ve ara yazılımı işlev uygulamanıza ekleme için geçerli .NET davranışlarını kullanabilirsiniz.
  • .NET sürüm esnekliği: Konak işleminin dışında çalışmak, işlevlerinizin .NET Framework dahil olmak üzere İşlevler çalışma zamanı tarafından yerel olarak desteklenmeyen .NET sürümlerinde çalışabileceği anlamına gelir.

Mevcut bir in-process C# işlev uygulamanız varsa, bu avantajlardan yararlanmak için uygulamanızı taşımak gerekir. Daha fazla bilgi için bkz. İç işlemler modelinden yalıtılmış çalışan modeline .NET uygulamaları taşıma.

İki mod arasındaki kapsamlı karşılaştırma için İşlem içi ve izole çalışan işlem .NET Azure İşlevleri arasındaki farklar bölümüne bakın.

Desteklenen sürümler

İşlevler çalışma zamanının sürümleri .NET belirli sürümlerini destekler. İşlev sürümleri hakkında daha fazla bilgi edinmek için bkz. Azure İşlevleri çalışma zamanı sürümlerine genel bakış. Sürüm desteği, işlevlerinizin işlem içinde mi yoksa yalıtılmış çalışan işlemi mi çalıştırdığına da bağlıdır.

Not

İşlev uygulamanız tarafından kullanılan İşlevler çalışma zamanı sürümünü değiştirmeyi öğrenmek için geçerli çalışma zamanı sürümünü görüntüleme ve güncelleştirme başlığına bakın.

Aşağıdaki tabloda, İşlevler'in belirli bir sürümüyle kullanılabilecek en yüksek .NET veya .NET Framework düzeyi gösterilmektedir.

İşlevler çalışma zamanı sürümü Yalıtılmış çalışan modeli İşlem içi model4
İşlevler 4.x1 .NET 105
.NET 9.0
.NET 8.0
.NET Framework 4.82		 .NET 8.0
İşlevler 1.x3 yok .NET Framework 4.8

1 .NET 6 daha önce her iki modelde de destekleniyordu ancak 12 Kasım 2024'te resmi destek süresinin sonuna ulaştı. .NET 7, daha önce yalıtılmış çalışan modelinde destekleniyordu ancak 14 Mayıs 2024'te resmi destek sonuna ulaştı.

2 Derleme işlemi ayrıca .NET SDK gerektirir.

3 Desteği, Azure İşlevleri çalışma zamanının 1.x sürümü için 14 Eylül 2026'da sona erer. Daha fazla bilgi için bkz. bu destek duyurusu. Sürekli tam destek için uygulamalarınızı 4.x sürümüne geçirmeniz gerekir.

4 Süreç içi model için destek 10 Kasım 2026'da sona erer. Daha fazla bilgi için bkz. bu destek duyurusu. Sürekli tam destek için uygulamalarınızı yalıtılmış çalışan modeline geçirmeniz gerekir.

5 Tüketim planında Linux üzerinde .NET 10 uygulamayı çalıştıramazsınız. Linux üzerinde çalıştırmak için bunun yerine Flex Consumption planını kullanmanız gerekir. Adım adım geçiş yönergeleri için bkz . Tüketim planı uygulamalarını Esnek Tüketim planına geçirme.

Belirli eski ikincil sürümlerin kaldırılması dahil olmak üzere Azure İşlevleri sürümleri hakkında en son haberler için Azure App Service duyurularını izleyin.

Project yapısı

Azure İşlevleri için yalıtılmış çalışan modelini kullanan bir .NET projesi, desteklenen bir .NET çalışma zamanını hedefleyen bir .NET konsol uygulaması projesidir. Aşağıdaki dosyalar, .NET yalıtılmış projelerde gereken temel dosyalardır:

  • project ve bağımlılıkları tanımlayan C# project dosyası (.csproj).
  • Program.cs dosyası, uygulamanın giriş noktasıdır.
  • İşlevlerinizi tanımlayan tüm kod dosyaları.
  • Projedeki işlevler arasında paylaşılan yapılandırmayı tanımlayan host.json dosyası.
  • makinenizde yerel olarak çalıştırıldığında project tarafından kullanılan ortam değişkenlerini tanımlayan local.settings.json dosyası.

Tam örnekler için bkz. .NET 8 örnek projesi ve .NET Framework 4.8 örnek projesi.

Paket bağıntıları

Yalıtılmış çalışan modelini kullanan Azure İşlevleri için .NET projesi, hem temel işlevler hem de bağlama uzantıları için benzersiz bir paket kümesi kullanır.

Çekirdek paketler

.NET işlevlerinizi yalıtılmış bir çalışan işleminde çalıştırmak için aşağıdaki paketlere ihtiyacınız vardır:

Bu paketlerin en düşük sürümleri hedef .NET sürümünüze bağlıdır:

.NET sürümü Microsoft.Azure.Functions.Worker Microsoft.Azure.Functions.Worker.Sdk
.NET 10 2.50.0 veya üzeri 2.0.5 veya üzeri
.NET 9 2.0.0 veya üzeri 2.0.0 veya üzeri
.NET 8 1.16.0 veya üzeri 1.11.0 veya üzeri
.NET Framework 1.16.0 veya üzeri 1.11.0 veya üzeri

Sürüm 2.x

Çekirdek paketlerin 2.x sürümleri desteklenen çerçeveleri değiştirir ve bu sonraki sürümlerden yeni .NET API'leri için destek getirir. 2.x sürümlerine güncelleştirirken aşağıdaki değişiklikleri not edin:

  • Microsoft.Azure.Functions.Worker.Sdk 2.0.0 sürümünden itibaren:
    • SDK, SDK kapsayıcı derlemeleri için varsayılan yapılandırmaları içerir.
    • SDK, dotnet run yüklendiğinde desteği içerir. Windows üzerinde, NPM tarafından kullanılmayan başka bir mekanizma aracılığıyla Çekirdek Araçları'nı yükleyin.
  • Microsoft.Azure.Functions.Worker 2.0.0 sürümünden başlayarak:
    • Bu sürüm IHostApplicationBuilder desteği ekler. Bu kılavuzdaki bazı örnekler, kullanarak IHostApplicationBuilderalternatifleri göstermek için sekmeler içerir. Bu örnekler için 2.x sürümleri gerekir.
    • Hizmet sağlayıcısı kapsam doğrulaması, bir geliştirme ortamında çalıştırılırsa varsayılan olarak dahil edilir. Bu davranış ASP.NET Core ile eşleşir.
    • Seçenek EnableUserCodeException varsayılan olarak etkindir. Özellik artık kullanım dışı olarak işaretlendi.
    • Seçenek IncludeEmptyEntriesInMessagePayload varsayılan olarak etkindir. Bu seçenek etkinleştirildiğinde, koleksiyonları temsil eden tetikleyici yükleri her zaman boş girdiler içerir. Örneğin, bir ileti gövde olmadan gönderilirse tetikleyici verileri için içinde boş bir giriş hala bulunur string[] . Boş girişlerin eklenmesi, işlevin de başvurabileceği meta veri dizileriyle çapraz başvuruda bulunmayı kolaylaştırır. Bu davranışı, IncludeEmptyEntriesInMessagePayload hizmet yapılandırmasında false olarak WorkerOptions ayarlayarak devre dışı bırakabilirsiniz.
    • ILoggerExtensions sınıfının adı FunctionsLoggerExtensions olarak değiştirildi. Yeniden adlandırma, LogMetric() bir örnekte kullanılırken belirsiz bir çağrı hatasını önler ILogger.
    • HttpResponseData kullanan uygulamalar için WriteAsJsonAsync() yöntemi artık durum kodunu 200 OK olarak ayarlar. 1.x'te bu davranış, ayarladığınız diğer hata kodlarını aşmış olur.
  • 2.x sürümleri, .NET 5 TFM desteğini bırakıyor.

Uzantı paketleri

Yalıtılmış .NET çalışan işlemi işlevleri farklı bağlama türleri kullandığından, benzersiz bir bağlama uzantısı paketleri kümesi gerektirir.

Bu uzantı paketlerini Microsoft.Azure altında bulabilirsiniz. Functions.Worker.Extensions.

Başlatma ve yapılandırma

Yalıtılmış çalışan modelini kullandığınızda, genellikle Program.cs'de olan işlev uygulamanızın başlatılmasına erişim sağlayabilirsiniz. Kendi konak örneğinizi oluşturmak ve başlatmaktan siz sorumlusunuz. Bu nedenle, uygulamanızın yapılandırma işlem hattına doğrudan erişim de vardır. .NET İşlevleri yalıtılmış çalışan işlemiyle yapılandırmaları çok daha kolay ekleyebilir, bağımlılıkları ekleyebilir ve kendi ara yazılımınızı çalıştırabilirsiniz.

kullanmak IHostApplicationBuilderiçin uygulamanızın çekirdek paketlerin 2.x veya sonraki bir sürümünü kullanması gerekir.

Aşağıdaki kodda bir IHostApplicationBuilder işlem hattı örneği gösterilmektedir:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

var host = builder.Build();

Build() üzerinde IHostApplicationBuilder çağırmadan önce şunları yapmalısınız:

  • ASP.NET Core tümleştirme kullanmak istiyorsanız builder.ConfigureFunctionsWebApplication() çağrısı yapın.
  • Uygulamanızı F# kullanarak yazıyorsanız, bazı bağlama uzantılarını kaydetmeniz gerekebilir. Bu uzantıları bir F# uygulamasında kullanmayı planlarken Blobs uzantısı, Tables uzantısı ve Cosmos DB uzantısı için kurulum belgelerine bakın.
  • Projenizin gerektirdiği hizmetleri veya uygulama yapılandırmasını yapılandırın. Ayrıntılar için bkz . Yapılandırma .
  • Application Insights'i kullanmayı planlıyorsanız, oluşturucunun AddOpenTelemetry().UseFunctionsWorkerDefaults() özelliğine karşı AddOpenTelemetry().UseAzureMonitorExporter() ve Services çağrısını yapmanız gerekir. Ayrıntılar için bkz . Application Insights .

Projeniz .NET Framework 4.8'i hedeflediyse, HostBuilder'ı oluşturmadan önce FunctionsDebugger.Enable(); eklemeniz gerekir. Yönteminizin Main() ilk satırı olmalıdır. Daha fazla bilgi için .NET Framework'ü Hedeflerken Hata Ayıklama bölümüne bakın.

IHostApplicationBuilder, işlev uygulamanızı zaman uyumsuz olarak başlatmak için çalıştırdığınız başlatılmış bir IHost örneğini derlemek ve döndürmek için kullanılır.

await host.RunAsync();

Yapılandırma

Kullandığınız oluşturucu türü, uygulamayı nasıl yapılandırabileceğinizi belirler.

İşlev uygulamasını çalıştırmak için gerekli ayarları eklemek üzere FunctionsApplication.CreateBuilder() metodunu kullanın. yöntemi aşağıdaki işlevleri içerir:

  • Varsayılan dönüştürücü kümesi.
  • Özellik adlarında büyük/küçük harfe dönüştürmeyi yoksaymak için varsayılan JsonSerializerOptions değerini ayarlayın.
  • Azure İşlevleri günlük kaydını tümleştirin.
  • Çıkış bağlama ara yazılımı ve özellikleri.
  • İşlev yürütme ara yazılımı.
  • Varsayılan gRPC desteği.
  • Host.CreateDefaultBuilder() uygulamasından diğer varsayılanları uygulayın.

Oluşturucu işlem hattına access, böylece başlatma sırasında uygulamaya özgü yapılandırmaları ayarlayabilirsiniz. Kodunuzun gerektirdiği yapılandırma kaynaklarını eklemek için oluşturucunun Configuration özelliğinde uzantı yöntemlerini çağırabilirsiniz. Uygulama yapılandırması hakkında daha fazla bilgi için bkz. ASP.NET Core'da Yapılandırma.

Bu yapılandırmalar yalnızca yazdığınız çalışan kodu için geçerlidir. İşlevler ana bilgisayarının veya tetikleyicilerin ve bağlamaların yapılandırmasını doğrudan etkilemez. konak veya tetikleyici ve bağlama yapılandırması işlevlerinde değişiklik yapmak için host.json dosyasını kullanın.

Not

Özel yapılandırma kaynakları tetikleyicilerin ve bağlamaların yapılandırması için kullanılamaz. Tetikleyici ve bağlama yapılandırması yalnızca uygulama kodunuz için değil İşlevler platformunda kullanılabilir olmalıdır. Bu yapılandırmayı application ayarları, Key Vault başvuruları veya App Yapılandırması başvuruları özellikleri aracılığıyla sağlayabilirsiniz.

Bağımlılık enjeksiyonu

Yalıtılmış çalışan modeli, hizmetleri eklemek için standart .NET mekanizmalarını kullanır.

IHostApplicationBuilder kullandığınızda, Services'a erişmek için özelliğini kullanın. Aşağıdaki örnek bir singleton hizmet bağımlılığını eklemektedir.

builder.Services.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();

Bu kod using Microsoft.Extensions.DependencyInjection; gerektirir. Daha fazla bilgi edinmek için ASP.NET Core'da Bağımlılık Enjeksiyonu başlığına bakın.

Azure istemcilerini kaydetme

Diğer Azure hizmetleriyle etkileşime geçmek için bağımlılık ekleme özelliğini kullanın. Azure SDK istemcilerini .NET için Microsoft.Extensions.Azure paketini kullanarak enjekte edebilirsiniz. Paketi yükledikten sonra, 'deki hizmet koleksiyonunda AddAzureClients() çağırarak istemcileri Program.cs. Aşağıdaki örnek, Azure Blobları için named client yapılandırıyor:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Azure;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddBlobServiceClient(builder.Configuration.GetSection("MyStorageConnection"))
                .WithName("copierOutputBlob");
        });

builder.Build().Run();

Aşağıdaki örnekte, eklenen istemciyi kullanarak blob içeriğini bir kapsayıcıdan diğerine akış olarak kopyalamak için bu kaydı ve SDK türlerini nasıl kullanabileceğiniz gösterilmektedir:

using Microsoft.Extensions.Azure;
using Microsoft.Extensions.Logging;

namespace MyFunctionApp
{
    public class BlobCopier
    {
        private readonly ILogger<BlobCopier> _logger;
        private readonly BlobContainerClient _copyContainerClient;

        public BlobCopier(ILogger<BlobCopier> logger, IAzureClientFactory<BlobServiceClient> blobClientFactory)
        {
            _logger = logger;
            _copyContainerClient = blobClientFactory.CreateClient("copierOutputBlob").GetBlobContainerClient("samples-workitems-copy");
            _copyContainerClient.CreateIfNotExists();
        }

        [Function("BlobCopier")]
        public async Task Run([BlobTrigger("samples-workitems/{name}", Connection = "MyStorageConnection")] Stream myBlob, string name)
        {
            await _copyContainerClient.UploadBlobAsync(name, myBlob);
            _logger.LogInformation($"Blob {name} copied!");
        }

    }
}

ILogger<T> Bu örnekteki de bağımlılık ekleme yoluyla elde edilir, bu nedenle otomatik olarak kaydedilir. Günlüğe kaydetme yapılandırma seçenekleri hakkında daha fazla bilgi edinmek için Günlüğe kaydetme bölümüne bakın.

İpucu

Örnekte, hem Program.cs'de hem de işlevde istemcinin adı için sabit bir dize kullanılır. Bunun yerine, işlev sınıfında tanımlanan paylaşılan bir sabit dize kullanmayı göz önünde bulundurun. Örneğin, public const string CopyStorageClientName = nameof(_copyContainerClient); ekleyebilir ve her iki konumda da BlobCopier.CopyStorageClientName başvurabilirsiniz. Yapılandırma bölümü adını Program.cs içinde değil, işlevle benzer şekilde tanımlayabilirsiniz.

Ara yazılım

Yalıtılmış çalışan modeli, ASP.NET'de bulunana benzer bir model kullanarak ara yazılım kaydını da destekler. Bu model, çağırma işlem hattına ve işlevlerin yürütülmesinden önce ve sonra mantık ekleme olanağı sağlar.

ConfigureFunctionsWorkerDefaults uzantısı yöntemi, aşağıdaki örnekte gördüğünüz gibi kendi ara yazılımınızı kaydetmenizi sağlayan bir aşırı yüklemeye sahiptir.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

// Register our custom middlewares with the worker
builder
    .UseMiddleware<ExceptionHandlingMiddleware>()
    .UseMiddleware<MyCustomMiddleware>()
    .UseWhen<StampHttpHeaderMiddleware>((context) =>
    {
        // We want to use this middleware only for http trigger invocations.
        return context.FunctionDefinition.InputBindings.Values
                        .First(a => a.Type.EndsWith("Trigger")).Type == "httpTrigger";
    });

builder.Build().Run();

UseWhen uzantı yöntemi, koşullu olarak yürütülen bir ara yazılımı kaydeder. Bu yönteme, boolean değeri geri döndüren bir koşul geçirmelisiniz. Ara yazılım, önermenin true döndürmesi durumunda çağrı işleme hattına katılır.

FunctionContext üzerindeki aşağıdaki uzantı yöntemleri, yalıtılmış modelde ara yazılımla çalışmayı kolaylaştırır.

Metot Açıklama
GetHttpRequestDataAsync HTTP tetikleyicisi HttpRequestData tarafından çağrıldığında bu örneği alır. Bu yöntem, ValueTask<HttpRequestData?> örneğini döndürür ve bu, istek başlıkları ve çerezler gibi ileti verilerini okumak istediğinizde işe yarar.
GetHttpResponseData HTTP tetikleyicisi HttpResponseData tarafından çağrıldığında bu örneği alır.
GetInvocationResult Mevcut işlev yürütmesinin sonucunu temsil eden InvocationResult bir örneği alır. Value Değeri gerektiği gibi almak veya ayarlamak için özelliğini kullanın.
GetOutputBindings Geçerli işlev yürütmesi için çıkış bağlama girdilerini alır. Bu yöntemin sonucundaki her girdi türündedir OutputBindingData. gerektiğinde değerini almak veya ayarlamak için özelliğini kullanabilirsiniz Value .
BindInputAsync İstenen BindingMetadata örnek için bir giriş bağlama öğesi bağlar. Örneğin, ara yazılımınız tarafından kullanılması gereken giriş bağlamasına sahip bir BlobInput işleviniz olduğunda bu yöntemi kullanın.

Bu örnekte örneği okuyan HttpRequestData ve işlev yürütme sırasında örneği güncelleştiren HttpResponseData bir ara yazılım uygulaması gösterilmektedir:

internal sealed class StampHttpHeaderMiddleware : IFunctionsWorkerMiddleware
{
    public async Task Invoke(FunctionContext context, FunctionExecutionDelegate next)
    {
        var requestData = await context.GetHttpRequestDataAsync();

        string correlationId;
        if (requestData!.Headers.TryGetValues("x-correlationId", out var values))
        {
            correlationId = values.First();
        }
        else
        {
            correlationId = Guid.NewGuid().ToString();
        }

        await next(context);

        context.GetHttpResponseData()?.Headers.Add("x-correlationId", correlationId);
    }
}

Bu ara yazılım, belirli bir istek üst bilgisinin (x-correlationId) varlığını denetler. Üst bilgi mevcut olduğunda ara yazılım, bir yanıt üst bilgisini damgalamak için üst bilgi değerini kullanır. Aksi takdirde, yeni bir GUID değeri oluşturur ve yanıt üst bilgisini damgalama için bu değeri kullanır.

İpucu

Tüm senaryolarda güvenilir şekilde çalışmayabilecek olan, await next(context) sonrasında yanıt üstbilgilerini ayarlama deseni daha önce gösterilmişti. Bu sorun özellikle ASP.NET Core tümleştirmesi kullanılırken veya yanıt akışının zaten gönderilmiş olabileceği belirli çalışma zamanı yapılandırmalarında geçerlidir. Üst bilgilerin doğru ayarlandığından emin olmak için, işlev context.GetInvocationResult().Value yürütme tamamlandıktan sonra ara yazılımda bunları değiştirmeye çalışmak yerine, yanıt işlevinizden döndürülmeden önce yanıt alma ve üst bilgileri ayarlamayı göz önünde bulundurun.

İşlev uygulamanızda özel ara yazılım kullanmanın daha eksiksiz bir örneği için bkz. custom ara yazılım başvuru örneği.

JSON serileştirmesini özelleştirme

Yalıtılmış çalışan modeli varsayılan olarak kullanır System.Text.Json . Hizmetleri dosyanızın Program.cs bir parçası olarak yapılandırarak seri hale getiricinin davranışını özelleştirebilirsiniz. Bu bölüm, genel amaçlı serileştirmeyi kapsar ve ASP.NET Core tümleştirme ile HTTP tetikleyici JSON serileştirmesini etkilemez, bu nedenle bunu ayrı olarak yapılandırmanız gerekir.

using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<JsonSerializerOptions>(jsonSerializerOptions =>
    {
        jsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        jsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
        jsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;

        // override the default value
        jsonSerializerOptions.PropertyNameCaseInsensitive = false;
    });

builder.Build().Run();

Serileştirme için JSON.NET (Newtonsoft.Json) kullanmak için Microsoft.Azure.Core.NewtonsoftJson paketini yükleyin. Ardından, hizmet kaydınızda Serializer yapılandırmasındaki WorkerOptions özelliğini yeniden atayın. Aşağıdaki örnek, ConfigureFunctionsWebApplication kullanarak bu yapılandırmayı gösterir, ancak ConfigureFunctionsWorkerDefaults için de çalışır.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<WorkerOptions>(workerOptions =>
    {
        var settings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
        settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
        settings.NullValueHandling = NullValueHandling.Ignore;

        workerOptions.Serializer = new NewtonsoftJsonObjectSerializer(settings);
    });

builder.Build().Run();

İşlev olarak tanınan yöntemler

İşlev yöntemi, aşağıdaki örnekte gösterildiği gibi yöntemine uygulanan bir Function özniteliği ve giriş parametresine tetikleyici özniteliği uygulanmış bir ortak sınıfın genel yöntemidir:

[Function(nameof(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Tetikleyici özniteliği tetikleyici türünü belirtir ve giriş verilerini bir yöntem parametresine bağlar. Yukarıdaki örnek işlev bir kuyruk iletisi tarafından tetiklenmiş ve kuyruk iletisi parametresindeki myQueueItem yöntemine geçirilir.

Function özniteliği, yöntemini bir işlev giriş noktası olarak işaretler. Ad bir project içinde benzersiz olmalı, bir harfle başlamalıdır ve en fazla 127 karakter uzunluğunda olmak üzere yalnızca harf, sayı, _ ve - içermelidir. Project şablonları genellikle Run adlı bir yöntem oluşturur, ancak yöntem adı geçerli bir C# yöntemi adı olabilir. yöntemi, bir ortak sınıfın genel üyesi olmalıdır. Hizmetlerin bağımlılık ekleme yoluyla geçirilebilmesi için genellikle bir örnek yöntemi olmalıdır.

İşlev parametreleri

İşlev yöntemi imzası kapsamında ekleyebileceğiniz parametrelerden bazıları şunlardır:

Yürütme bağlamı

Yalıtılmış çalışan modelinde, çalışan işlemi işlev yöntemlerinize bir FunctionContext nesnesi geçirir. Bu nesne, ILogger yöntemini çağırarak ve bir dizesi sağlayarak günlüklere yazmak üzere bir categoryName örneği almanızı sağlar. Bağımlılık ekleme kullanmak zorunda kalmadan bir ILogger elde etmek için bu bağlamı kullanabilirsiniz. Daha fazla bilgi için bkz. Logging.

İptal belirteçleri

İşlev cancellationToken parametresini kabul edebilir ve bu parametre, işletim sisteminin işlev sonlandırılacakken kodunuzu bildirmesini sağlar. İşlevin verileri tutarsız bir durumda bırakabilecek şekilde beklenmedik şekilde sonlandırılmadığından emin olmak için bu bildirimi kullanabilirsiniz.

Yalıtılmış bir çalışan işleminde çalışan .NET işlevleri iptal belirteçlerini destekler. Aşağıdaki örnek, iptal isteği alındığında bir özel durum oluşturur:

[Function(nameof(ThrowOnCancellation))]
public async Task ThrowOnCancellation(
    [EventHubTrigger("sample-workitem-1", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(ThrowOnCancellation));

    foreach (var message in messages)
    {
        cancellationToken.ThrowIfCancellationRequested();
        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

Aşağıdaki örnek, bir iptal isteği alındığında temizleme eylemleri gerçekleştirir:

[Function(nameof(HandleCancellationCleanup))]
public async Task HandleCancellationCleanup(
    [EventHubTrigger("sample-workitem-2", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(HandleCancellationCleanup));

    foreach (var message in messages)
    {
        if (cancellationToken.IsCancellationRequested)
        {
            _logger.LogInformation("A cancellation token was received, taking precautionary actions.");
            // Take precautions like noting how far along you are with processing the batch
            _logger.LogInformation("Precautionary activities complete.");
            break;
        }

        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

İptale yol açan senaryolar

İşlev çağrısı iptal edildiğinde iptal belirteci işaret edilir. Çeşitli nedenler iptale neden olabilir ve bu nedenler kullanılan tetikleyici türüne bağlı olarak değişir. Yaygın nedenlerden bazıları şunlardır:

  • İstemci bağlantısını kesme: İşlevinizi çağıran istemcinin bağlantısı kesilir. Bu neden büyük olasılıkla HTTP tetikleyici işlevleri içindir.
  • İşlev uygulamasının yeniden başlatılması: Siz veya platform, bir çağrı talep edildiğinde, işlev uygulamasını yeniden başlatır veya durdurur. Yeniden başlatma, çalışan örneği taşımaları, çalışan örneği güncelleştirmeleri veya ölçeklendirme nedeniyle oluşabilir.

İptal konusunda dikkat edilmesi gerekenler

  • Yeniden başlatma olayı sırasında yapılan çağrılar, nasıl tetiklendiğine bağlı olarak yeniden denenebilir. Daha fazla bilgi için yeniden deneme belgelerine bakın.

  • Ana bilgisayarın çağrı isteğini çalışana gönderebilmesi için iptal belirteci iptal edilmiş olsa bile, ana bilgisayar çağrıyı çalışana gönderir.

  • Önceden iptal edilmiş çağrıların çalışana gönderilmesini istemiyorsanız, bu davranışı devre dışı bırakmak için özelliğini dosyanıza SendCanceledInvocationsToWorker ekleyinhost.json.

    Bu örnekte bu özelliği kullanan bir host.json dosya gösterilmektedir:

    {
    "version": "2.0",
    "SendCanceledInvocationsToWorker": "false"
}

  • SendCanceledInvocationsToWorker ayarının false olarak ayarlanması, aşağıdaki günlükle bir FunctionInvocationCanceled özel duruma neden olabilir:

    İptal istendi. Kimliği '{invocationId}' olan çağırma isteği iptal edildi ve çalışana gönderilmez.

    Bu özel durum, (daha önce açıklanan olaylardan birinin sonucu olarak) iptal belirteci iptal edildiğinde, konak çalışana gelen bir çağırma isteği göndermeden önce oluşur. Bu özel durum güvenle yoksayılabilir ve SendCanceledInvocationsToWorker olduğunda false beklenir.

Asenkron programlama

.NET yalıtılmış çalışanı özel bir SynchronizationContext ayarlamaz. Bu, işlev yürütme sırasında SynchronizationContext.Current'nin null olduğu anlamına gelir. await sonra, standart .NET davranışı olan iş parçacığı havuzunda devam işlemleri zamanlanır.

Gizlenecek bir şey olmadığından SynchronizationContext işlev kodunuzda kullanmanın ConfigureAwait(false) pratik bir etkisi yoktur. Yalıtılmış çalışan işlemi, standart bir .NET genel ana bilgisayar (konsol uygulaması) olarak çalıştığından, herhangi bir ASP.NET Core veya konsol uygulamasında görmeyi beklediğiniz aynı asinxron/await davranışı burada geçerlidir. Bu, .NET Framework (net48) yalıtılmış çalışan uygulamaları için de geçerlidir çünkü çalışan işlemi her zaman HostBuilder kullanan bir konsol yürütülebilir dosyasıdır.

Not

Dayanıklı İşlevler düzenleyicilerin kendi iş parçacığı kısıtlamaları vardır. Orkestratör yeniden yürütme iş parçacığının devamlılıkları çalıştırması gerekir, bu nedenle orkestratör işlevlerinde veya ara yazılımında ConfigureAwait(false) kullanılması yürütmeyi bozabilir. Daha fazla bilgi için bkz. Dayanıklı İşlevler kod kısıtlamaları.

Bağlamalar

Yöntemler, parametreler ve dönüş türleri üzerindeki öznitelikleri kullanarak bağlamaları tanımlayın. Bağlamalar verileri dizeler, diziler ve düz eski sınıf nesneleri (POCO' lar) gibi serileştirilebilir türler olarak sağlayabilir. Bazı bağlama uzantıları için, hizmet SDK'larında tanımlanan hizmete özgü türlere de bağlanabilirsiniz.

HTTP tetikleyicileri için HTTP tetikleyicisi bölümüne bakın.

Yalıtılmış çalışan işlemi işlevlerinin tetikleyicileri ve bağlantı uzantılarını kullanan eksiksiz bir başvuru örnekleri kümesi için bkz. bağlantı uzantıları başvuru örneği.

Giriş bağlamaları

bir işlev, işleve veri geçiren sıfır veya daha fazla giriş bağlamasına sahip olabilir. Tetikleyiciler gibi, giriş parametresine bağlama özniteliği uygulayarak giriş bağlamaları tanımlarsınız. İşlev yürütürken, çalışma zamanı bağlamada belirtilen verileri almaya çalışır. İstenen veriler genellikle tetikleyici tarafından bağlama parametreleri aracılığıyla sağlanan bilgilere bağlıdır.

Çıkış bağlamaları

Çıkış bağlamasına yazmak için işlev yöntemine bir çıkış bağlama özniteliği uygulamanız gerekir. Bu öznitelik, bağlı hizmete yazma işlemini tanımlar. Yöntemin dönüş değeri çıkış bağlamasına yazılır. Örneğin, aşağıdaki örnek bir çıkış bağlaması kullanarak adlı output-queue ileti kuyruğuna bir dize değeri yazar:

[Function(nameof(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

Birden çok çıkış bağlaması

Çıkış bağlamasına yazılan veriler her zaman işlevin dönüş değeridir. Birden fazla çıkış bağlamasına yazmanız gerekiyorsa, özel bir dönüş türü oluşturmanız gerekir. Bu dönüş türü, sınıfın bir veya daha fazla özelliğine uygulanan çıkış bağlama özniteliğine sahip olmalıdır. HTTP ile tetiklenen ve ASP.NET Core tümleştirmesi kullanan aşağıdaki örnek, hem HTTP yanıtına hem de kuyruk çıkış bağlamasına yazan bir işlevdir.

public class MultipleOutputBindings
{
    private readonly ILogger<MultipleOutputBindings> _logger;

    public MultipleOutputBindings(ILogger<MultipleOutputBindings> logger)
    {
        _logger = logger;
    }

    [Function("MultipleOutputBindings")]
    public MyOutputType Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
    {
        _logger.LogInformation("C# HTTP trigger function processed a request.");
        var myObject = new MyOutputType
        {
            Result = new OkObjectResult("C# HTTP trigger function processed a request."),
            MessageText = "some output"
        };
        return myObject;
    }

    public class MyOutputType
    {
        [HttpResult]
        public IActionResult Result { get; set; }

        [QueueOutput("myQueue")]
        public string MessageText { get; set; }
    }
}

ASP.NET Core tümleştirmesi ile birden çok çıkış bağlaması için özel dönüş türleri kullandığınızda, sonucu sağlayan özelliğe [HttpResult] özniteliğini eklemeniz gerekir. HttpResult özniteliği, SDK 1.17.3-preview2 veya daha üstü ile birlikte HTTP uzantısının 3.2.0 veya daha üstü ve ASP.NET Core uzantısının 1.3.0 veya daha üstü sürümünü kullanırken erişilebilir.

SDK türleri

Hizmete özgü bazı bağlama türleri için, hizmet SDK'larından ve çerçevelerinden türleri kullanarak bağlama verileri sağlayabilirsiniz. Bu türler, serileştirilmiş bir dizenin veya düz eski CLR nesnesinin (POCO) sağlayabileceklerinin ötesinde özellikler sunar. Daha yeni türleri kullanmak için project temel bağımlılıkların daha yeni sürümlerini kullanacak şekilde güncelleştirin.

Bağımlılık Sürüm gereksinimi
Microsoft.Azure. Functions.Worker 1.18.0 veya üzeri
Microsoft.Azure. Functions.Worker.Sdk 1.13.0 veya üzeri

SDK türlerini makinenizde yerel olarak test ederken Azure İşlevleri Core Tools, sürüm 4.0.5000 veya üzerini de kullanmanız gerekir. komutunu kullanarak func --version geçerli sürümünüzü de kontrol edebilirsiniz.

Her bağlama uzantısının, uzantı başvuru makalelerinde açıklanan kendi en düşük sürüm gereksinimi de vardır. Bu bağlama uzantıları şu anda SDK türlerini desteklemektedir:

Extension Türler Destek düzeyi
Azure Blob Depolama BlobClient
BlobContainerClient
BlockBlobClient
PageBlobClient
AppendBlobClient		 Tetikleyici: GA
Giriş: GA
Azure Cosmos DB CosmosClient
Database
Container		 Giriş: GA
Azure Event Grid CloudEvent
EventGridEvent		 Tetikleyici: GA
Azure Event Hubs EventData
EventHubProducerClient		 Tetikleyici: GA
Azure Kuyruk Depolama QueueClient
QueueMessage		 Tetikleyici: GA
Azure Service Bus ServiceBusClient
ServiceBusReceiver
ServiceBusSender
ServiceBusMessage		 Tetikleyici: GA
Azure Tablo Depolaması TableClient
TableEntity		 Giriş: GA

SDK türleri için dikkat edilmesi gerekenler:

  • Tetikleyici verilerini kullanan bağlama ifadeleri kullanılırken, tetikleyicinin kendisi için SDK türleri kullanılamaz.
  • SDK türü kullanabileceğiniz çıkış senaryoları için, çıktı bağlaması kullanmak yerine doğrudan SDK istemcileri oluşturun ve bu istemcilerle çalışın.
  • Azure Cosmos DB tetikleyicisi Azure Cosmos DB değişiklik akışını kullanır ve değişiklik akışı öğelerini JSON serileştirilebilir türler olarak kullanıma sunar. Sonuç olarak, SDK türleri bu tetikleyici için desteklenmez.

HTTP tetikleyicisi

HTTP tetikleyicileri , bir işlevin bir HTTP isteği tarafından çağrılmasına olanak tanır. İki farklı yaklaşım kullanabilirsiniz:

ASP.NET Core tümleştirmesi

Bu bölümde, HttpRequest, HttpResponse ve IActionResult gibi ASP.NET Core türlerini kullanarak temel alınan HTTP isteği ve yanıt nesneleriyle nasıl çalışabilirsiniz? Bu model, .NET Framework hedefleyen apps tarafından kullanılamaz ve bunun yerine built-in modeli kullanılmalıdır.

Not

Bu model, ASP.NET Core tüm özelliklerini kullanıma sunmaz. Özellikle, ASP.NET Core ara yazılım işlem hattına ve yönlendirme özelliklerine erişim sağlamaz. ASP.NET Core tümleştirme, güncelleştirilmiş paketleri kullanmanızı gerektirir.

HTTP için ASP.NET Core tümleştirmesini etkinleştirmek için:

  1. Projenizde Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore paketine, sürüm 1.0.0 veya üzeri, bir referans ekleyin.

  2. Projenizi belirtilen özel paket sürümlerini kullanacak şekilde güncelleyin.

  3. Dosyanızda, Program.cs üzerinde değişiklik yaparak ConfigureFunctionsWebApplication()'yi çağıracak şekilde konak oluşturucu yapılandırmasını güncelleyin. Bu yöntem, aksi takdirde kullanacağınız ConfigureFunctionsWorkerDefaults()'nin yerini alır. Aşağıdaki örnekte, diğer özelleştirmeler olmadan minimum kurulum gösterilmektedir:

    Not

    Uygulamanızın, Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore sürüm 2.0.0 veya daha yenisine başvurması gerekiyor IHostApplicationBuilder ile ASP.NET Core tümleştirmesini kullanabilmek için.

    using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();    

builder.Build().Run();

  4. ASP.NET Core türlerini kullanmak için mevcut HTTP ile tetiklenen işlevleri güncelleştirin. Bu örnekte, basit bir "hello, world" işlevi için kullanılan standart HttpRequest ve IActionResult gösterilmektedir.

    [Function("HttpFunction")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req)
{
    return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
}

ASP.NET Core tümleştirmesi ile JSON serileştirmesi

ASP.NET Core kendi serileştirme katmanı vardır ve genel serileştirme yapılandırmasını özelleştirmeden etkilenmez. HTTP tetikleyicileriniz için kullanılan serileştirme davranışını özelleştirmek için hizmet kaydının bir parçası olarak bir .AddMvc() çağrı eklemeniz gerekir. Döndürülen IMvcBuilder, ASP.NET Core JSON serileştirme ayarlarını değiştirmek için kullanılabilir.

ASP.NET tümleştirmesini kullanırken HttpRequestData ve HttpResponseData kullanmaya devam edebilirsiniz, ancak çoğu uygulama için bunun yerine HttpRequest ve IActionResult kullanmak daha iyidir. HttpRequestData / HttpResponseData kullanılması ASP.NET Core serileştirme katmanını çağırmaz ve bunun yerine uygulama için genel çalışan serileştirme yapılandırmasına dayanır. Ancak ASP.NET Core tümleştirme etkinleştirildiğinde yapılandırma eklemeniz gerekebilir. ASP.NET Core'un varsayılan davranışı, senkron GÇ'ye izin vermemektir. gibi NewtonsoftJsonObjectSerializerzaman uyumsuz GÇ'yi desteklemeyen özel bir seri hale getirici kullanmak için, öğesini yapılandırarak uygulamanız için zaman uyumlu GÇ'yi KestrelServerOptionsetkinleştirmeniz gerekir.

Aşağıdaki örnek, bu yaklaşımı kullanarak seri hale getirme için JSON.NET (Newtonsoft.Json) ve Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet paketinin nasıl yapılandırılacağını göstermektedir.

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Services.AddMvc().AddNewtonsoftJson();

// Only needed if using HttpRequestData/HttpResponseData and a serializer that doesn't support asynchronous IO
// builder.Services.Configure<KestrelServerOptions>(options => options.AllowSynchronousIO = true);

builder.Build().Run();

Yerleşik HTTP modeli

Yerleşik modelde sistem, gelen HTTP isteği iletisini işleve geçirdiği bir HttpRequestData nesnesine çevirir. Bu nesne, Headers, Cookies, Identities, URL ve isteğe bağlı olarak bir ileti Body dahil olmak üzere istekten veri sağlar. Bu nesne HTTP isteğini temsil eder, ancak temel alınan HTTP dinleyicisine veya alınan iletiye doğrudan bağlı değildir.

Önemli

Eğer HttpRequestData kullanıyorsanız, HTTP isteğinin gövdesi bir akış olamaz. Örneğin, isteğin Transfer-Encoding: chunked üst bilgisi varsa ve Content-Length üst bilgisi yoksa, HttpRequestData nesnesinin Body özelliği null bir akış olur. Akış HTTP istekleriyle çalışmanız gerekiyorsa bunun yerine ASP.NET Core tümleştirme modelini kullanmayı göz önünde bulundurun.

Benzer şekilde işlev, http yanıtını oluşturmak için kullanılan ileti , StatusCode ve isteğe bağlı olarak bir ileti Headers içeren bir Body nesnesi döndürür.

Aşağıdaki örnek, HttpRequestData ve HttpResponseData kullanımını göstermektedir.

[Function(nameof(HttpFunction))]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger(nameof(HttpFunction));
    logger.LogInformation("message logged");

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to .NET isolated worker !!");

    return response;
}

Kayıt Tutma

ILogger<T> veya ILogger örneğini kullanarak günlüklere yazabilirsiniz. Bir hizmet ya da bir ILoggerFactory'nin bağımlılık enjeksiyonuILogger<T> yoluyla günlükçüye ulaşabilirsiniz:

public class MyFunction {
    
    private readonly ILogger<MyFunction> _logger;
    
    public MyFunction(ILogger<MyFunction> logger) {
        _logger = logger;
    }
    
    [Function(nameof(MyFunction))]
    public void Run([BlobTrigger("samples-workitems/{name}", Connection = "")] string myBlob, string name)
    {
        _logger.LogInformation($"C# Blob trigger function Processed blob\n Name: {name} \n Data: {myBlob}");
    }

}

Not

Önceki örnekte olduğu gibi sınıf oluşturucunuza bir ILogger<T> eklediğinizde, günlük kategorisi otomatik olarak bu sınıfın tam adına, örneğin MyFunctionApp.MyFunction, ayarlanır. Bu kategori adları . nokta karakterleri içerir. İşlev uygulamanızı Linux'ta barındırdığınızda, dönem içeren kategorilerin günlük düzeylerini geçersiz kılmak için ortam değişkenlerini kullanamazsınız. Bu sınırlamayı aşmak için bunun yerine kodunuzda veya bir dosyada günlük düzeylerini yapılandırabilirsiniz.

FunctionContext nesnesinden geçen bir nesneden kayıt tutucuyu da alabilirsiniz. GetLogger<T> veya GetLogger yöntemini çağırarak günlüklerin yazıldığı kategorinin adı olan dize değerini geçirin. Kategori genellikle günlüklerin yazıldığı belirli işlevin adıdır. Kategoriler hakkında daha fazla bilgi için izleme makalesine bakın.

Çeşitli günlük düzeylerini, ILogger<T> veya ILogger gibi, LogWarning veya LogError yöntemlerini kullanarak yazın. Günlük düzeyleri hakkında daha fazla bilgi için gözlem makalesine bakın. Filtreleri kaydederek kodunuza eklenen bileşenlerin günlük düzeylerini özelleştirebilirsiniz:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

// Registers IHttpClientFactory.
// By default this sends a lot of Information-level logs.
builder.Services.AddHttpClient();

// Disable IHttpClientFactory Informational logs.
// Note -- you can also remove the handler that does the logging: https://github.com/aspnet/HttpClientFactory/issues/196#issuecomment-432755765 
builder.Logging.AddFilter("System.Net.Http.HttpClient", LogLevel.Warning);
    
builder.Build().Run();

Uygulamanızı Program.cs içinde yapılandırırken, hataların günlüklere nasıl yansıtılacağını gösteren davranışı da tanımlayabilirsiniz. Varsayılan davranış, kullandığınız oluşturucunun türüne bağlıdır.

IHostApplicationBuilder kullandığınızda, kodunuz tarafından atılan özel durumlar, değişiklik olmaksızın sistemden geçer. Başka bir yapılandırmaya ihtiyacınız yoktur.

Uygulama Öngörüleri

Yalıtılmış işlem uygulamanızı, günlükleri doğrudan Application Insights adresine gönderecek şekilde yapılandırabilirsiniz. Bu yapılandırma, günlüklerin konak üzerinden iletilmesi işleminin varsayılan davranışını değiştirir. Aspire kullanmıyorsanız, doğrudan Application Insights entegrasyonunu yapılandırın zira bu, günlüklerin nasıl yayıldığı üzerinde size kontrol imkanı tanır.

Application Insights tümleştirmesi tüm kurulum deneyimlerinde varsayılan olarak etkinleştirilmez. Bazı şablonlar, gerekli paketlerin ve başlangıç kodunun açıklama eklendiği İşlev projeleri oluşturur. Application Insights tümleştirmesini kullanmak istiyorsanız, Program.cs ve project .csproj dosyasında bu satırların açıklamasını kaldırın. Bu bölümün geri kalanındaki yönergelerde tümleştirmenin nasıl etkinleştirileceği de açıklanmaktadır.

Eğer projeniz bir Aspire orchestration'ın bir parçasıysa, bunun yerine izleme için OpenTelemetry kullanıyor. Aspire projelerinin içinde doğrudan Application Insights tümleştirmesini etkinleştirmeyin. Bunun yerine, Azure İzleyici OpenTelemetry ihracatçısını hizmet varsayılanları projesinin bir parçası olarak yapılandırın. İşlevler projeniz bir Aspire bağlamında Application Insights entegrasyonu kullanıyorsa, başlangıçta uygulama hataları oluşur.

host.json dosyasını güncelle

İşlevler konağından OpenTelemetry çıkışını etkinleştirmek için kod projenizdeki host.json dosyasını güncelleştirerek kök koleksiyona bir "telemetryMode": "OpenTelemetry" öğe ekleyin. OpenTelemetry etkinleştirildiğinde, host.json dosyanız aşağıdaki gibi görünebilir:

{
    "version": "2.0",
    "telemetryMode": "OpenTelemetry",
    ...
}

Paketleri yükleme

Kodunuzda doğrudan Application Insights'a günlük yazmak için projenize bu paketlere referanslar ekleyin.

Bu referansları projenize eklemek için aşağıdaki komutları çalıştırınız.

dotnet add package Microsoft.Azure.Functions.Worker.OpenTelemetry
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

Başlangıcı yapılandır

Paketleri yükledikten sonra, aşağıdaki örnekte gösterildiği gibi dosyanızın AddOpenTelemetry().UseFunctionsWorkerDefaults() dosyasında hizmet yapılandırması sırasında AddOpenTelemetry().UseAzureMonitorExporter() ve Program.cs'i çağırın.

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
    
var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();
builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Build().Run();

Daha fazla bilgi edinmek için bkz. Azure İşlevleri ile OpenTelemetry kullanma.

Günlük düzeylerini yönet

Önemli

İşlevler ana bilgisayarı ve yalıtılmış işlem çalışanı günlük düzeyleri için ayrı yapılandırmaya sahiptir. host.json'deki herhangi bir yapılandırma, çalışanın günlüğünü etkilemez ve benzer şekilde, çalışan kodunuzdaki yapılandırma da konak günlüğünü etkilemez. Senaryonuz her iki katmanda da özelleştirme gerektiriyorsa değişiklikleri her iki yerde de uygulayın.

Yalıtılmış çalışan işleminde günlük düzeylerini şu yollardan biriyle yapılandırabilirsiniz:

Yapılandırma yöntemi Fayda -ları
Kodunuzda Ana bilgisayar tarafı ve çalışan tarafı yapılandırmaları arasında daha net bir ayrım sağlar.
appsettings.json’ı kullanma Kodunuzu değiştirmek zorunda kalmadan farklı kategoriler için farklı günlük düzeyleri ayarlamak istediğinizde kullanışlıdır.

FunctionsApplication.CreateBuilder() otomatik olarak appsettings.json dosyalarından yapılandırmayı yükler. Dosyanıza appsettings.json günlük yapılandırmasını ekleyebilirsiniz.

{
  "logging": {
    "logLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Azure.Functions.Worker": "Information"
    }
  }
}

Oluşturucuyu oluşturduğunuzda bu yapılandırma otomatik olarak uygulanır. Program.cs içinde ilave bir kod değişikliği gerekmez:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Build().Run();

Günlüğe kaydetmeyi yapılandırma hakkında daha fazla bilgi için bkz. .NET'te Logging ve Worker Service uygulamaları için Application Insights.

Performansta iyileştirmeler

Bu bölümde, soğuk başlangıç ile ilgili performansı geliştiren etkinleştirebileceğiniz seçenekler özetlenmiştir.

Genel olarak, uygulamanız temel bağımlılıklarının en son sürümlerini kullanmalıdır. Projenizi en azından aşağıdaki gibi güncelleyin:

  1. Microsoft.Azure.Functions.Worker’ı sürüm 1.19.0 veya daha üstüne güncelleyin.
  2. Microsoft.Azure.Functions.Worker.Sdk'yi 1.16.4 veya daha yeni bir sürüme yükseltin.
  3. Uygulamanız .NET Framework'ü hedeflemedikçe Microsoft.AspNetCore.App için bir çerçeve başvurusu ekleyin.

Aşağıdaki kod parçacığı bu yapılandırmayı bir project dosyası bağlamında gösterir:

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
  </ItemGroup>

Yer tutucular

Yer tutucular, .NET 6 veya daha sonraki sürümleri hedefleyen uygulamalar için soğuk başlangıcı geliştiren bir platform özelliğidir. Bu iyileştirmeyi kullanmak için aşağıdaki adımları izleyerek yer tutucuları açıkça etkinleştirmeniz gerekir:

  1. project yapılandırmanızı, önceki bölümde açıklandığı gibi en son bağımlılık sürümlerini kullanacak şekilde güncelleştirin.

  2. WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED uygulama ayarını 1 olarak ayarlayın. Bu az functionapp config appsettings set komutunu kullanın:

    az functionapp config appsettings set -g <groupName> -n <appName> --settings 'WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED=1'

    Bu örnekte, <groupName> kaynak grubunun adıyla ve <appName> fonksiyon uygulamanızın adıyla değiştirin.

  3. İşlev uygulamasının netFrameworkVersion özelliğinin projenizin 6 veya daha sonraki .NET olması gereken hedef çerçevesiyle eşleştiğinden emin olun. Bu az functionapp config set komutunu kullanın:

    az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

    Bu örnekte, <framework> hedef .NET sürümüne göre v8.0 gibi uygun sürüm dizesiyle de değiştirin.

  4. İşlev uygulamanızın 64 bitlik bir işlem kullanacak şekilde yapılandırıldığından emin olun. Bu az functionapp config set komutunu kullanın:

    az functionapp config set -g <groupName> -n <appName> --use-32bit-worker-process false

Önemli

olarak ayarlanırken WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED1, diğer tüm işlev uygulaması yapılandırmalarını doğru ayarlamanız gerekir. Aksi takdirde işlev uygulamanız başlatılamaz.

İyileştirilmiş yürütücü

İşlev yürütücüsü, çağırmaların çalışmasına neden olan platformun bir bileşenidir. Bu bileşenin iyileştirilmiş bir sürümü, SDK'nın 1.16.2 sürümünden başlayarak varsayılan olarak etkinleştirilir. Başka yapılandırma gerekmez.

ReadyToRun

İşlev uygulamanızı ReadyToRun ikili dosyaları olarak derleyebilirsiniz. ReadyToRun, başlangıç performansını geliştirerek bir Tüketim planında çalışırken soğuk başlangıçların etkisini azaltmaya yardımcı olabilen bir zamanından önce derleme yöntemidir. ReadyToRun, .NET 6 ve sonraki sürümlerde kullanılabilir ve Azure İşlevleri çalışma zamanının version 4.0 veya üzeri gerektirir.

ReadyToRun, barındırma uygulamasının çalışma zamanı mimarisine göre project derlemenizi gerektirir. Bu mimariler hizalanmamışsa, uygulamanız başlangıçta bir hatayla karşılaşır. Bu tablodan çalışma zamanı tanımlayıcınızı seçin:

İşletim Sistemi Uygulama 32-bit1 Çalışma zamanı tanımlayıcısı
Windows Doğru win-x86
Windows Yanlış win-x64
Linux işletim sistemi Doğru Yok (desteklenmez)
Linux işletim sistemi Yanlış linux-x64

1 Yalnızca 64 bit uygulamalar diğer bazı performans iyileştirmeleri için uygundur.

Windows uygulamanızın 32 bit mi yoksa 64 bit mi olduğunu denetlemek için, aşağıdaki CLI komutunu çalıştırın ve <group_name> yerine kaynak grubunuzun adını, <app_name> yerine uygulamanızın adını yazın. "true" çıkışı, uygulamanın 32 bit, "false" ise 64 bit olduğunu gösterir.

 az functionapp config show -g <group_name> -n <app_name> --query "use32BitWorkerProcess"

Aynı değiştirmeleri kullanarak aşağıdaki komutla uygulamanızı 64 bit olarak değiştirebilirsiniz:

az functionapp config set -g <group_name> -n <app_name> --use-32bit-worker-process false`

project ReadyToRun olarak derlemek için <PublishReadyToRun> ve <RuntimeIdentifier> öğelerini ekleyerek project dosyanızı güncelleştirin. Aşağıdaki örnekte, Windows 64 bit işlev uygulamasına yayımlamaya yönelik bir yapılandırma gösterilmektedir.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>

project dosyasının parçası olarak <RuntimeIdentifier> ayarlamak istemiyorsanız, bu ayarı yayımlama hareketinin bir parçası olarak da yapılandırabilirsiniz. Örneğin, Windows 64 bit işlev uygulamasıyla .NET CLI komutu şöyledir:

dotnet publish --runtime win-x64

Visual Studio yayımlama profilindeki Target Runtime seçeneğini doğru çalışma zamanı tanımlayıcısına ayarlayın. Taşınabilir varsayılan değerine ayarlandığında ReadyToRun kullanılmaz.

Azure İşlevleri'a dağıtım yap

İşlev kodu projenizi Azure dağıttığınızda, proje bir işlev uygulamasında veya Linux kapsayıcısında çalıştırılmalıdır. Kodunuzu dağıtmadan önce işlev uygulamasını ve diğer gerekli Azure kaynaklarını oluşturmanız gerekir.

İşlev uygulamanızı bir Linux kapsayıcısında da dağıtabilirsiniz. Daha fazla bilgi için bkz. Kapsayıcılarla çalışma ve Azure İşlevleri.

Azure kaynakları oluşturma

aşağıdaki yöntemlerden birini kullanarak işlev uygulamanızı ve diğer gerekli kaynakları Azure oluşturabilirsiniz:

  • Visual Studio: Visual Studio kod yayımlama işlemi sırasında sizin için kaynak oluşturabilir.
  • Visual Studio Code: Visual Studio Code aboneliğinize bağlanabilir, uygulamanız için gereken kaynakları oluşturabilir ve ardından kodunuzu yayımlayabilir.
  • Azure CLI: Azure gerekli kaynakları oluşturmak için Azure CLI kullanın.
  • Azure PowerShell: Azure'da gerekli kaynakları oluşturmak için Azure PowerShell kullanın.
  • Deployment şablonları: GEREKLI kaynakların Azure dağıtımını otomatikleştirmek için ARM şablonlarını ve Bicep dosyalarını kullanın. Şablonunuzun gerekli ayarları içerdiğine emin olun.
  • Azure portalı: Azure portalında gerekli kaynakları oluşturun.

Uygulamanızı yayımlama

Azure'de işlev uygulamanızı ve diğer gerekli kaynakları oluşturduktan sonra aşağıdaki yöntemlerden birini kullanarak kod projesini Azure dağıtın:

Daha fazla bilgi için bkz. deployment technologies in Azure İşlevleri.

Dağıtım yükü

Dağıtım yöntemlerinin çoğu zip arşivi kullanır. Zip arşivini kendiniz oluşturursanız, bu bölümde açıklanan yapıyı izlemesi gerekir. Aksi takdirde, uygulamanız başlangıçta hatalarla karşılaşabilir.

Dağıtım yükü, kapsayan üst klasör olmadan bir dotnet publish komutun çıktısı ile eşleşmelidir. Zip arşivi aşağıdaki dosyalardan oluşturulmalıdır:

  • .azurefunctions/
  • extensions.json
  • functions.metadata
  • host.json
  • worker.config.json
  • Projenizin yürütülebilir dosyası (konsol uygulaması)
  • Diğer destekleyici dosyalar ve dizinler bu yürütülebilir dosyayla aynı seviyede yer alır.

Derleme işlemi bu dosyaları oluşturur ve bunları doğrudan düzenlememeniz gerekir.

İpucu

Dağıtım için doğru bir zip arşivi oluşturmak için Core Tools'taki komutunu kullanabilirsiniz func pack . Şu anda func pack için bu destek önizleme aşamasındadır.

Dağıtım için bir zip arşivi hazırlarken, kapsayan dizinin kendisini değil, yalnızca çıkış dizininin içeriğini sıkıştırın. Arşiv geçerli çalışma dizinine ayıklandığında, daha önce listelenen dosyaların hemen görünür olması gerekir.

Dağıtım gereksinimleri

Azure'da yalıtılmış çalışan modelinde .NET işlevleri çalıştırmak için birkaç gereksinimi karşılamanız gerekir. Gereksinimler işletim sistemine bağlıdır:

İşlev uygulamanızı önceki bölümdeki yöntemleri kullanarak Azure oluşturduğunuzda, bu gerekli ayarlar sizin için eklenir. Arm şablonlarını veya otomasyon için Bicep dosyaları kullanarak bu kaynakları oluşturduğunuzda bunları şablonda ayarladığınızdan emin olmanız gerekir.

Aspire

Aspire , bulutta dağıtılmış uygulamaların geliştirilmesini basitleştiren, fikirli bir yığındır. Yalıtılmış çalışan modeli projelerini Aspire 13 orkestrasyonlarına kaydedebilirsiniz. Daha fazla bilgi için Aspire ile Azure İşlevleri konusuna bakın.

Hata ayıklama

Visual Studio veya Visual Studio Code kullanarak yerel olarak çalışırken, yalıtılmış .NET çalışan projenizde normal şekilde hata ayıklayabilirsiniz. Ancak, beklendiği gibi çalışmayan iki hata ayıklama senaryosu vardır.

Visual Studio kullanarak Uzaktan Hata Ayıklama

Yalıtılmış çalışan işlemi uygulamanız İşlevler çalışma zamanının dışında çalıştığından, uzak hata ayıklayıcıyı ayrı bir işleme eklemeniz gerekir. Visual Studio kullanarak hata ayıklama hakkında daha fazla bilgi edinmek için bkz. Remote Debugging.

.NET Framework hedeflenirken hata ayıklama

Yalıtılmış projeniz .NET Framework 4.8'i hedef alıyorsa, hata ayıklamayı etkinleştirmek için el ile adım atmalısınız. Başka bir hedef çerçeve kullanılıyorsa bu adımlar gerekli değildir.

Uygulamanız ilk işlemi olarak FunctionsDebugger.Enable();'u çağrı yaparak başlamalıdır. Bu, bir HostBuilder başlatmadan önce Main() yönteminde gerçekleşir. Dosyanız Program.cs şuna benzer görünmelidir:

using System;
using System.Diagnostics;
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;
using NetFxWorker;

namespace MyDotnetFrameworkProject
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

            var host = FunctionsApplication
                .CreateBuilder(args)
                .Build();

            host.Run();
        }
    }
}

Ardından, işleme manuel olarak ekleme yapmak için bir .NET Framework hata ayıklayıcı kullanmanız gerekir. Visual Studio, yalıtılmış çalışan işlemi .NET Framework uygulamaları için bunu otomatik olarak gerçekleştirmez ve "Hata Ayıklamayı Başlat" işleminden kaçınılmalıdır.

project dizininizde (veya derleme çıktı dizininde) komutunu çalıştırın:

func host start --dotnet-isolated-debug

Bu işlem çalışanınızı başlatır ve işlem şu iletiyle durdurulur:

Azure Functions .NET Worker (PID: <process id>) initialized in debug mode. Waiting for debugger to attach...

Çalışan işleminizin kimliği <process id>'dir. Artık işlemi el ile bağlamak için Visual Studio'yu kullanabilirsiniz. Bu işlemle ilgili yönergeler için Çalışan bir sürece nasıl eklenir bölümüne bakın.

Hata ayıklayıcı eklendikten sonra işlem yürütmesi devam eder ve hata ayıklaması yapabileceksiniz.

.NET sürümlerini önizleme

Genel kullanıma sunulan bir sürümden önce .NET sürümü Preview veya Go-live durumunda yayınlanabilir. Bu durumlarla ilgili ayrıntılar için .NET Resmi Destek İlkesi bakın.

Yerel İşlevler projesinden belirli bir sürümü hedeflemek mümkün olsa da, Azure barındırılan işlev uygulamalarında bu sürüm kullanılamayabilir. Azure İşlevleri yalnızca bu bölümde not edilen Önizleme veya Canlıya Alma sürümleriyle kullanılabilir.

Azure İşlevleri şu anda "Önizleme" veya "Go-live" .NET sürümleriyle çalışmıyor. Kullanabileceğiniz genel kullanıma sunulan sürümlerin listesi için bkz . Desteklenen sürümler .

Önizleme .NET SDK'sı kullanma

.NET önizleme sürümüyle Azure İşlevleri kullanmak için projenizi şu şekilde güncelleştirmeniz gerekir:

  1. Geliştirmenizde ilgili .NET SDK sürümünü yükleme
  2. TargetFramework Dosyanızdaki .csproj ayarı değiştirme

Azure'da işlev uygulamanıza dağıttığınızda, çerçevenin uygulama için kullanılabilir hale getirildiğinden de emin olmanız gerekir. Önizleme döneminde, bazı araçlar ve deneyimler yeni önizleme sürümünü bir seçenek olarak göstermeyebilir. Azure portalında önizleme sürümünü görmüyorsanız, sürümü el ile yapılandırmak için REST API, Bicep dosyaları veya Azure CLI kullanabilirsiniz.

Windows üzerinde barındırılan uygulamalar için aşağıdaki Azure CLI komutunu kullanın. <groupName>'yu kaynak grubunun adıyla ve <appName>'yi işlev uygulamanızın adıyla değiştirin. <framework> ifadesini uygun sürüm dizesi olan v8.0 ile değiştirin.

az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

.NET önizleme sürümlerini kullanma konusunda dikkat edilmesi gerekenler

.NET önizleme sürümleriyle İşlevler'i kullanırken şu noktaları göz önünde bulundurun:

  • İşlevlerinizi Visual Studio yazarken, .NET önizleme SDK'larıyla Azure İşlevleri projeleri oluşturmayı destekleyen Visual Studio Insider kullanmanız gerekir.

  • En son İşlevler araçlarına ve şablonlarına sahip olduğunuzdan emin olun. Araçlarınızı güncelleştirmek için:

    1. Tools>Options, Projects and Solutions> altında Azure İşlevleri öğesini seçin.
    2. Güncelleştirmeleri denetle seçeneğini belirleyin ve istendiğinde güncelleştirmeleri yükleyin.

  • Önizleme döneminde geliştirme ortamınız barındırılan hizmetten daha yeni bir .NET önizleme sürümüne sahip olabilir. Bu, dağıtıldığında işlev uygulamanızın başarısız olmasına neden olabilir. Bu sorunu gidermek için, içinde global.jsonkullanılacak SDK sürümünü belirtebilirsiniz.

    1. dotnet --list-sdks komutunu çalıştırın ve yerel geliştirme sırasında kullanmakta olduğunuz önizleme sürümünü not edin.
    2. dotnet new globaljson --sdk-version <SDK_VERSION> --force Komutunu çalıştırın. Burada<SDK_VERSION>, yerel olarak kullandığınız sürümdür. Örneğin dotnet new globaljson --sdk-version dotnet-sdk-10.0.100-preview.5.25277.114 --force, projenizi oluştururken sistemin .NET 10 Preview 5 SDK'sını kullanmasına neden olur.

Not

Önizleme çerçevelerinin tam zamanında yüklenmesi nedeniyle, Windows üzerinde çalışan işlev uygulamaları, önceki GA sürümlerine kıyasla daha fazla soğuk başlangıç süresiyle karşılaşabilir.

Sonraki adımlar

Azure İşlevleri

.NET uygulamaları yalıtılmış çalışan modeline geçir

Aspire ile tümleştirme

  • Last updated on