// Chain order: Environment → WorkloadIdentity → ManagedIdentity →
//              VisualStudio → AzureCLI → AzurePowerShell → AzureDeveloperCLI

// Sviluppo: rileva automaticamente l'identità disponibile
var credential = new DefaultAzureCredential();

// Produzione: identità user-assigned esplicita
var credential = new ManagedIdentityCredential(
    ManagedIdentityId.FromUserAssignedClientId(config["ManagedIdentityClientId"]));

// DI: una sola istanza condivisa tra tutti i client
builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.UseCredential(new DefaultAzureCredential());
    clientBuilder.AddSecretClient(new Uri(config["KeyVault:Url"]));
    clientBuilder.AddServiceBusClientWithNamespace(config["ServiceBus:Namespace"]);
});

// Errori comuni: AuthenticationFailedException, CredentialUnavailableException

// Singleton — riusa connessioni tra invocazioni
services.AddSingleton(sp =>
    new ServiceBusClient(config["ServiceBus:Namespace"], new DefaultAzureCredential()));

// Safe batching
await using var sender = client.CreateSender(queueName);
using ServiceBusMessageBatch batch = await sender.CreateMessageBatchAsync();
foreach (var msg in messages)
    if (!batch.TryAddMessage(new ServiceBusMessage(msg)))
        throw new InvalidOperationException("Message too large for batch");
await sender.SendMessagesAsync(batch);

// Background processing — AutoCompleteMessages = false per controllo manuale
var processor = client.CreateProcessor(queueName, new ServiceBusProcessorOptions
    { AutoCompleteMessages = false, MaxConcurrentCalls = 4 });
processor.ProcessMessageAsync += async args => {
    // ... logica
    await args.CompleteMessageAsync(args.Message); // o AbandonMessageAsync
};

// Dead Letter: SubQueue.DeadLetter su receiver separato
// Ordering: SessionId sul messaggio + AcceptNextSessionAsync
// Errori: ServiceBusException.Reason per diagnostica specifica

// KeyClient per gestione chiavi, CryptographyClient per operazioni crypto
var keyClient = new KeyClient(new Uri(kvUrl), new DefaultAzureCredential());
var cryptoClient = new CryptographyClient(keyId, new DefaultAzureCredential());

// Crea chiave con scadenza e operazioni limitate
var key = await keyClient.CreateRsaKeyAsync(new CreateRsaKeyOptions("my-key")
{
    ExpiresOn = DateTimeOffset.UtcNow.AddYears(1),
    KeyOperations = { KeyOperation.Encrypt, KeyOperation.Decrypt }
});

// Encrypt/Decrypt
var encrypted = await cryptoClient.EncryptAsync(EncryptionAlgorithm.RsaOaep256, plaintext);
var decrypted = await cryptoClient.DecryptAsync(EncryptionAlgorithm.RsaOaep256, encrypted.Ciphertext);

// Sign/Verify (hash interno — non pre-hashare)
var sig = await cryptoClient.SignDataAsync(SignatureAlgorithm.RS256, data);
var valid = await cryptoClient.VerifyDataAsync(SignatureAlgorithm.RS256, data, sig.Signature);

// Rotation automatica con policy
await keyClient.RotateKeyAsync("my-key");
// RBAC: Key Vault Crypto Officer (gestione) · Key Vault Crypto User (operazioni)

// SearchClient → query e CRUD documenti
// SearchIndexClient → gestione indici e schema
// SearchIndexerClient → indexer e skillset

// Indice type-safe con attributi
public class MyDoc {
    [SimpleField(IsKey = true)] public string Id { get; set; }
    [SearchableField(IsSortable = true)] public string Title { get; set; }
    [VectorSearchField(VectorSearchDimensions = 1536, VectorSearchProfileName = "default")]
    public IReadOnlyList<float> Embedding { get; set; }
}

// Vector search
var results = await searchClient.SearchAsync<MyDoc>(null, new SearchOptions
{
    VectorSearch = new VectorSearchOptions
    {
        Queries = { new VectorizedQuery(embedding)
            { KNearestNeighborsCount = 10, Fields = { "Embedding" } } }
    }
});

// Hybrid: vector + keyword + semantic ranking nella stessa chiamata
var hybrid = await searchClient.SearchAsync<MyDoc>("query", new SearchOptions
{
    QueryType = SearchQueryType.Semantic,
    VectorSearch = new VectorSearchOptions
    {
        Queries = { new VectorizedQuery(embedding) { Fields = { "Embedding" } } }
    }
});

// Batch upload/merge/delete
await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Create(
        IndexDocumentsAction.Upload(doc1),
        IndexDocumentsAction.MergeOrUpload(doc2),
        IndexDocumentsAction.Delete("id", "key3")));

undefined

undefined

undefined

- `Decisioni chiave`: architettura, storage, pattern, target cloud, boundary
- `Assunzioni`: prerequisiti tecnici resi espliciti
- `Rischi`: sempre con severity `HIGH|MEDIUM|LOW`
- `Blocchi`: sempre `BLOCKER`
- `Artefatti prodotti`: codice, test, IaC, docker, documentazione
- `Handoff al prossimo agente`: richiesto solo se target o boundary restano ambigui

undefined

undefined